Pocketenv CLI#

The official CLI for Pocketenv — create, manage, and connect to isolated sandboxes from your terminal. Powered by AT Protocol for open, portable, and vendor-agnostic sandbox definitions.

💡 Use Cases#

• Run AI agents (Codex, Claude, Gemini, OpenClaw, Copilot ...) safely in isolated environments
• Spin up ephemeral dev sandboxes for quick prototyping
• Share reproducible developer environments via AT Protocol
• Test untrusted or third-party code securely
• Provide sandbox infrastructure as a service

🚚 Installation#

# Build and install locally
npm run build && npm install -g .

Or install globally

npm install -g @pocketenv/cli

pnpm add -g @pocketenv/cli

bun add -g @pocketenv/cli

Verify the installation:

pocketenv --version

⚡ Quick Start#

# 1. Log in with your AT Proto account (e.g. Bluesky)
pocketenv login <handle>.bsky.social

# 2. Create a sandbox
pocketenv create

# 3. Start it
pocketenv start <sandbox-name>

# 4. Open an interactive shell inside it
pocketenv console <sandbox-name>

🔐 Authentication#

Pocketenv uses AT Protocol for authentication. You need an AT Proto account (e.g. a Bluesky account) to use the CLI.

🔑 Login#

pocketenv login <handle>

Authenticates with your AT Proto handle. A browser window will open for you to authorize the app. Your session token is saved locally at ~/.pocketenv/token.json.

Example:

pocketenv login alice.bsky.social

👤 Whoami#

pocketenv whoami

Displays the currently logged-in user.

🚪 Logout#

pocketenv logout

Removes your local session token.

🛠️ Commands#

📦 Sandbox Management#

pocketenv create [name]#

Create a new sandbox. Aliases: new

pocketenv create my-sandbox
pocketenv create my-sandbox --provider cloudflare

Supported providers: cloudflare, daytona, deno, vercel, sprites.

pocketenv ls#

List all your sandboxes with their status and creation time.

pocketenv ls

Output example:

NAME                    BASE          STATUS    CREATED AT
true-punter-0nan        openclaw      RUNNING   33 minutes ago
ruinous-straw-wz8n      nix           STOPPED   2 days ago
narrative-shift-j80dx   zeroclaw      STOPPED   11 days ago
mad-ambulance-k9eu      nullclaw      STOPPED   11 days ago
revered-amateur-n6rz    opencrust     STOPPED   11 days ago
high-priced-vac-ek73    picoclaw      STOPPED   11 days ago

pocketenv start <sandbox>#

Start a stopped sandbox.

pocketenv start my-sandbox

pocketenv stop <sandbox>#

Stop a running sandbox.

pocketenv stop my-sandbox

pocketenv rm <sandbox>#

Delete a sandbox permanently. Aliases: delete, remove

pocketenv rm my-sandbox

🖥️ Interactive Shell#

pocketenv console [sandbox]#

Open an interactive shell inside a running sandbox. Aliases: shell, ssh, s

# Connect to a specific sandbox
pocketenv console my-sandbox

# Omit the name to auto-connect to the first running sandbox
pocketenv console

🌍 Environment Variables#

Manage environment variables scoped to a sandbox.

pocketenv env put <sandbox> <key> <value>#

Set an environment variable.

pocketenv env put my-sandbox DATABASE_URL postgres://localhost/mydb

pocketenv env list <sandbox>#

List all environment variables for a sandbox. Aliases: ls

pocketenv env list my-sandbox
pocketenv env ls my-sandbox

pocketenv env delete <variable_id>#

Remove an environment variable. Aliases: rm, remove

pocketenv env delete var_d6qt6q8d60de420001jf

🤫 Secrets#

Manage encrypted secrets scoped to a sandbox.

pocketenv secret put <sandbox> <key>#

Store a secret in a sandbox (value is prompted securely).

pocketenv secret put my-sandbox API_KEY

pocketenv secret list <sandbox>#

List all secret keys stored in a sandbox. Aliases: ls

pocketenv secret list my-sandbox

pocketenv secret delete <secret_id>#

Delete a secret from a sandbox. Aliases: rm, remove

pocketenv secret delete secret_d6qt6q8d60de420000jg

🗝️ SSH Keys#

Manage SSH keys associated with a sandbox.

pocketenv sshkeys put <sandbox>#

Upload an SSH key pair to a sandbox.

pocketenv sshkeys put my-sandbox

pocketenv sshkeys get <sandbox>#

Retrieve the public SSH key from a sandbox.

pocketenv sshkeys get my-sandbox

🔒 Tailscale#

Manage Tailscale integration for your sandboxes.

pocketenv tailscale put <sandbox>#

Store a Tailscale auth key in a sandbox.

pocketenv tailscale put my-sandbox

pocketenv tailscale get <sandbox>#

Retrieve the stored Tailscale auth key (redacted) from a sandbox.

pocketenv tailscale get my-sandbox

💾 Backups#

Create and restore point-in-time backups of sandbox directories.

pocketenv backup create <sandbox> <directory>#

Create a backup of a directory inside a sandbox.

pocketenv backup create my-sandbox /workspace
pocketenv backup create my-sandbox /workspace --description "pre-deploy" --ttl 7d

pocketenv backup list <sandbox>#

List all backups for a sandbox. Aliases: ls

pocketenv backup list my-sandbox
pocketenv backup ls my-sandbox

Output example:

BACKUP ID                  DIRECTORY   CREATED AT       EXPIRES AT
bkp_01jqwerty123456789     /app        2 hours ago      in 3 days

pocketenv backup restore <backup_id>#

Restore a sandbox from a backup.

pocketenv backup restore bkp_01jqwerty123456789

⚙️ Configuration#

The CLI can be configured via the following environment variables:

Example — using a token in CI:

POCKETENV_TOKEN=<your-token> pocketenv ls

📚 Documentation#

Full documentation is available at docs.pocketenv.io.

🤝 Contributing#

Contributions are welcome! Please read the Contributing Guidelines before submitting a pull request.

• Bug reports & feature requests: Open an issue
• Community & feedback: Join our Discord

📄 License#

Mozilla Public License 2.0