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.

[!NOTE] Still in development

This project is in early development. Expect breaking changes and rapid iteration.

💡 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

| Option | Description | |-----------------------------|---------------------------------------------| | --provider, -p <provider> | The provider to use (default: cloudflare) |

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.

| Option | Description | |-----------------|-----------------------------| | --private-key | Path to the SSH private key | | --public-key | Path to the SSH public key | | --generate | Generate a new key pair |

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

⚙️ Configuration

The CLI can be configured via the following environment variables:

| Variable | Default | Description | |---------------------|----------------------------|-----------------------------------------------| | POCKETENV_TOKEN | (none) | Override the session token (useful for CI/CD) | | POCKETENV_API_URL | https://api.pocketenv.io | Override the API base URL | | POCKETENV_CF_URL | https://sbx.pocketenv.io | Override the Cloudflare sandbox URL | | POCKETENV_TTY_URL | https://api.pocketenv.io | Override the TTY URL |

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