AgentKey

Your personal AI coding agent, on any Mac or Linux machine.

AgentKey is a portable AI agent environment that lives on a USB drive. Plug it into a computer, open a terminal, run agent, and your encrypted provider setup, skills, memories, MCP config, and operating habits come with you.

It is not just "an AI assistant on a USB stick." AgentKey is a portable agent identity and runtime: a way to carry your own Codex-style terminal agent between machines without reinstalling and reconfiguring everything each time.

Why AgentKey

Modern coding agents are powerful, but their setup is not portable. Every new computer usually means installing a CLI, adding API keys, configuring providers, syncing skills, recreating MCP servers, and rebuilding memory.

AgentKey turns that into a one-time bootstrap:

1. Prepare the USB drive on your main computer.
2. Configure your provider and encrypted vault.
3. Bootstrap your local Codex skills, memories, and MCP config.
4. Use the same agent profile on any supported Mac or Linux machine.

After bootstrap, other computers do not automatically merge their local Codex data into your USB. Your portable profile stays yours. When you intentionally want to refresh it from your main computer, run agent sync.

Product Positioning

AgentKey is a portable AI agent runtime for developers and agent power users.

It is designed for people who:

• switch between multiple computers
• work in labs, classrooms, client machines, remote servers, or hackathons
• need DeepSeek, OpenRouter, OpenAI, or OpenAI-compatible providers
• want their skills, memory, MCP config, and preferred agent behavior to travel with them
• do not want to leave API keys or agent history scattered across host machines

The short pitch:

Plug in AgentKey. Your agent is back.

Advantages

• Portable by default
  Runs from a USB drive on macOS and Linux. The host machine only needs Python 3 and network access.

• Personal agent profile
  Carries your skills, memories, agents, MCP/plugin config sections, model preferences, and portable Codex config.

• Encrypted API vault
  API credentials are stored in agentkey/secrets/secrets.env.age, encrypted with an age passphrase. The release payload does not include user keys.

• Provider gateway
  Codex talks to a local Responses-compatible gateway; the gateway translates requests to OpenAI-compatible /chat/completions APIs.

• China-friendly provider path
  DeepSeek, OpenRouter, OpenAI, and custom OpenAI-compatible endpoints are first-class setup choices.

• One-time bootstrap, explicit refresh
  First setup can bootstrap your local Codex data. Later, agent sync explicitly refreshes the portable profile. agent sync --plugins is available when you also want large plugin caches.

• Release packages for different needs
  full, macos, linux, and lite archives are published. The lite package downloads the current platform runtime during install.

• Diagnostics included
  agent status, agent doctor, and agent test-provider help diagnose runtime, vault, provider, and sync issues.

Quick Start

Download the latest archive from Releases:

• agentkey-usb-demo-0.3.3-full.tar.gz for macOS + Linux runtimes
• agentkey-usb-demo-0.3.3-macos.tar.gz for macOS only
• agentkey-usb-demo-0.3.3-linux.tar.gz for Linux only
• agentkey-usb-demo-0.3.3-lite.tar.gz for a tiny installer that fetches runtime on install

Install to a USB drive:

tar -xzf agentkey-usb-demo-0.3.3-full.tar.gz
cd agentkey-release
./install-to-usb.sh

You can also pass the mount path explicitly:

./install-to-usb.sh /Volumes/USB
./install-to-usb.sh /media/$USER/USB

Start from the USB:

cd /Volumes/USB
./start

Ubuntu example:

cd /media/$USER/USB
./start

Daily Use

Run AgentKey in a project directory:

./agent --cd ~/Downloads

If you installed the one-word shell command:

agent --cd ~/Downloads

Check status:

agent status

Test the configured provider:

agent test-provider

Run a one-shot task:

agent exec --skip-git-repo-check "Read this project and summarize it"

Bootstrap And Sync

On your main computer, first setup can bootstrap your local Codex profile into AgentKey:

• skills
• memories
• agents
• AGENTS.md
• models_cache.json
• [features], [plugins.*], and [mcp_servers.*] config sections

It intentionally skips:

• auth.json
• sessions and archived sessions
• SQLite state databases
• logs and temp files
• OAuth tokens

To refresh the portable profile later:

agent sync

To also copy large plugin caches and external skill repos:

agent sync --plugins

Profile Portability

Export your portable profile:

agent profile export

Import it into another AgentKey drive:

agent profile import agentkey-profile-YYYYMMDD-HHMMSS.tar.gz

The profile archive includes the encrypted vault and portable agent data, but still avoids plaintext API keys and generated Codex session state.

Commands

agent status
agent doctor
agent doctor --provider
agent test-provider
agent sync
agent sync --plugins
agent profile show
agent profile export
agent profile import <archive.tar.gz>
agent update

Requirements

• macOS arm64/x64 or Linux arm64/x64
• Python 3 on the host computer
• Network access to your provider
• A provider API key

Provider Support

Current setup choices:

• DeepSeek
• OpenRouter
• OpenAI
• Custom OpenAI-compatible endpoint

The gateway currently targets OpenAI-compatible /chat/completions APIs. Native Anthropic Claude, Gemini, DashScope, and other non-compatible APIs need dedicated adapters.

Security Model

AgentKey keeps provider credentials in an encrypted age vault:

agentkey/secrets/secrets.env.age

The repository and release payload are designed not to include user API keys, OAuth tokens, sessions, or SQLite state. Release validation checks for common accidental leaks before publishing.

Repository Layout

agentkey-release/
  AgentKey-USB/          USB payload scripts and portable home template
  scripts/               build, test, and publish helpers
  docs/                  demo script and supporting docs
SHA256SUMS               release asset checksums

Runtime binaries are not committed to git because they are large. They are included in GitHub Release assets, and the lite package can fetch runtime binaries during installation.

Build And Test

Build release archives:

cd agentkey-release
./scripts/build-release.sh

Run release validation:

./scripts/test-release.sh

Publish with GitHub CLI:

./scripts/publish-github-release.sh davidpengrj/agentkey

Current Status

AgentKey is an early demo/alpha. It is already usable for macOS/Linux USB workflows, but the product surface is still intentionally simple and terminal-first.

Near-term roadmap:

• native Claude/Gemini/DashScope adapters
• faster in-place updater for large personalized drives
• optional unlock session cache
• richer MCP/skills management
• hardware shell/status display experiments