pocketenv.io / pocketenv
the universal sandbox runtime for agents and humans. pocketenv.io
sandbox openclaw agent claude-code vercel-sandbox deno-sandbox cloudflare-sandbox atproto sprites daytona
7
fork

Configure Feed

Select the types of activity you want to include in your feed.

pocketenv / apps / cli / README.md
at main 390 lines 8.8 kB view raw view rendered
Tsiry Sandratraina Add sandbox backup commands and docs
286a72f6
1# Pocketenv CLI 2 3[![npm version](https://img.shields.io/npm/v/@pocketenv/cli?color=green)](https://www.npmjs.com/package/@pocketenv/cli) 4![NPM Downloads](https://img.shields.io/npm/dw/%40pocketenv%2Fcli) 5[![discord](https://img.shields.io/discord/1270021300240252979?label=discord&logo=discord&color=5865F2)](https://discord.gg/9ada4pFUFS) 6[![License: MPL-2.0](https://img.shields.io/badge/License-MPL_2.0-blue.svg)](https://opensource.org/licenses/MPL-2.0) 7 8 ![Made with VHS](https://vhs.charm.sh/vhs-1y1YqClWEmOwPD3MFwp40V.gif) 9 10The official CLI for [Pocketenv](https://pocketenv.io) — create, manage, and connect to isolated sandboxes from your terminal. Powered by [AT Protocol](https://atproto.com) for open, portable, and vendor-agnostic sandbox definitions. 11 12> [!NOTE] 13> **Still in development** 14> 15> This project is in early development. Expect breaking changes and rapid iteration. 16 17--- 18 19## 💡 Use Cases 20 21- Run AI agents (Codex, Claude, Gemini, OpenClaw, Copilot ...) safely in isolated environments 22- Spin up ephemeral dev sandboxes for quick prototyping 23- Share reproducible developer environments via [AT Protocol](https://atproto.com) 24- Test untrusted or third-party code securely 25- Provide sandbox infrastructure as a service 26 27--- 28 29## 🚚 Installation 30 31```sh 32# Build and install locally 33npm run build && npm install -g . 34``` 35 36Or install globally 37 38```sh 39npm install -g @pocketenv/cli 40``` 41 42```sh 43pnpm add -g @pocketenv/cli 44``` 45 46```sh 47bun add -g @pocketenv/cli 48``` 49 50Verify the installation: 51 52```sh 53pocketenv --version 54``` 55 56## ⚡ Quick Start 57 58```sh 59# 1. Log in with your AT Proto account (e.g. Bluesky) 60pocketenv login <handle>.bsky.social 61 62# 2. Create a sandbox 63pocketenv create 64 65# 3. Start it 66pocketenv start <sandbox-name> 67 68# 4. Open an interactive shell inside it 69pocketenv console <sandbox-name> 70``` 71 72## 🔐 Authentication 73 74Pocketenv uses [AT Protocol](https://atproto.com) for authentication. You need an AT Proto account (e.g. a [Bluesky](https://bsky.app) account) to use the CLI. 75 76### 🔑 Login 77 78```sh 79pocketenv login <handle> 80``` 81 82Authenticates 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`. 83 84**Example:** 85 86```sh 87pocketenv login alice.bsky.social 88``` 89 90### 👤 Whoami 91 92```sh 93pocketenv whoami 94``` 95 96Displays the currently logged-in user. 97 98### 🚪 Logout 99 100```sh 101pocketenv logout 102``` 103 104Removes your local session token. 105 106--- 107 108## 🛠️ Commands 109 110### 📦 Sandbox Management 111 112#### `pocketenv create [name]` 113 114Create a new sandbox. Aliases: `new` 115 116| Option | Description | 117|-----------------------------|---------------------------------------------| 118| `--provider, -p <provider>` | The provider to use (default: `cloudflare`) | 119 120```sh 121pocketenv create my-sandbox 122pocketenv create my-sandbox --provider cloudflare 123``` 124 125Supported providers: `cloudflare`, `daytona`, `deno`, `vercel`, `sprites`. 126 127--- 128 129#### `pocketenv ls` 130 131List all your sandboxes with their status and creation time. 132 133```sh 134pocketenv ls 135``` 136 137Output example: 138 139``` 140NAME BASE STATUS CREATED AT 141true-punter-0nan openclaw RUNNING 33 minutes ago 142ruinous-straw-wz8n nix STOPPED 2 days ago 143narrative-shift-j80dx zeroclaw STOPPED 11 days ago 144mad-ambulance-k9eu nullclaw STOPPED 11 days ago 145revered-amateur-n6rz opencrust STOPPED 11 days ago 146high-priced-vac-ek73 picoclaw STOPPED 11 days ago 147``` 148 149--- 150 151#### `pocketenv start <sandbox>` 152 153Start a stopped sandbox. 154 155```sh 156pocketenv start my-sandbox 157``` 158 159--- 160 161#### `pocketenv stop <sandbox>` 162 163Stop a running sandbox. 164 165```sh 166pocketenv stop my-sandbox 167``` 168 169--- 170 171#### `pocketenv rm <sandbox>` 172 173Delete a sandbox permanently. Aliases: `delete`, `remove` 174 175```sh 176pocketenv rm my-sandbox 177``` 178 179--- 180 181### 🖥️ Interactive Shell 182 183#### `pocketenv console [sandbox]` 184 185Open an interactive shell inside a running sandbox. Aliases: `shell`, `ssh`, `s` 186 187```sh 188# Connect to a specific sandbox 189pocketenv console my-sandbox 190 191# Omit the name to auto-connect to the first running sandbox 192pocketenv console 193``` 194 195--- 196 197### 🌍 Environment Variables 198 199Manage environment variables scoped to a sandbox. 200 201#### `pocketenv env put <sandbox> <key> <value>` 202 203Set an environment variable. 204 205```sh 206pocketenv env put my-sandbox DATABASE_URL postgres://localhost/mydb 207``` 208 209#### `pocketenv env list <sandbox>` 210 211List all environment variables for a sandbox. Aliases: `ls` 212 213```sh 214pocketenv env list my-sandbox 215pocketenv env ls my-sandbox 216``` 217 218#### `pocketenv env delete <variable_id>` 219 220Remove an environment variable. Aliases: `rm`, `remove` 221 222```sh 223pocketenv env delete var_d6qt6q8d60de420001jf 224``` 225 226--- 227 228### 🤫 Secrets 229 230Manage encrypted secrets scoped to a sandbox. 231 232#### `pocketenv secret put <sandbox> <key>` 233 234Store a secret in a sandbox (value is prompted securely). 235 236```sh 237pocketenv secret put my-sandbox API_KEY 238``` 239 240#### `pocketenv secret list <sandbox>` 241 242List all secret keys stored in a sandbox. Aliases: `ls` 243 244```sh 245pocketenv secret list my-sandbox 246``` 247 248#### `pocketenv secret delete <secret_id>` 249 250Delete a secret from a sandbox. Aliases: `rm`, `remove` 251 252```sh 253pocketenv secret delete secret_d6qt6q8d60de420000jg 254``` 255 256--- 257 258### 🗝️ SSH Keys 259 260Manage SSH keys associated with a sandbox. 261 262#### `pocketenv sshkeys put <sandbox>` 263 264Upload an SSH key pair to a sandbox. 265 266| Option | Description | 267|-----------------|-----------------------------| 268| `--private-key` | Path to the SSH private key | 269| `--public-key` | Path to the SSH public key | 270| `--generate` | Generate a new key pair | 271 272```sh 273pocketenv sshkeys put my-sandbox 274``` 275 276#### `pocketenv sshkeys get <sandbox>` 277 278Retrieve the public SSH key from a sandbox. 279 280```sh 281pocketenv sshkeys get my-sandbox 282``` 283 284--- 285 286### 🔒 Tailscale 287 288Manage Tailscale integration for your sandboxes. 289 290#### `pocketenv tailscale put <sandbox>` 291 292Store a Tailscale auth key in a sandbox. 293 294```sh 295pocketenv tailscale put my-sandbox 296``` 297 298#### `pocketenv tailscale get <sandbox>` 299 300Retrieve the stored Tailscale auth key (redacted) from a sandbox. 301 302```sh 303pocketenv tailscale get my-sandbox 304``` 305 306--- 307 308### 💾 Backups 309 310Create and restore point-in-time backups of sandbox directories. 311 312#### `pocketenv backup create <sandbox> <directory>` 313 314Create a backup of a directory inside a sandbox. 315 316| Option | Description | 317|-------------------------------|----------------------------------------------------| 318| `--description, -d <text>` | Optional description for the backup | 319| `--ttl, -t <duration>` | Time-to-live (e.g. `10m`, `2h`, `7d`; default `3d`) | 320 321```sh 322pocketenv backup create my-sandbox /workspace 323pocketenv backup create my-sandbox /workspace --description "pre-deploy" --ttl 7d 324``` 325 326--- 327 328#### `pocketenv backup list <sandbox>` 329 330List all backups for a sandbox. Aliases: `ls` 331 332```sh 333pocketenv backup list my-sandbox 334pocketenv backup ls my-sandbox 335``` 336 337Output example: 338 339``` 340BACKUP ID DIRECTORY CREATED AT EXPIRES AT 341bkp_01jqwerty123456789 /app 2 hours ago in 3 days 342``` 343 344--- 345 346#### `pocketenv backup restore <backup_id>` 347 348Restore a sandbox from a backup. 349 350```sh 351pocketenv backup restore bkp_01jqwerty123456789 352``` 353 354--- 355 356## ⚙️ Configuration 357 358The CLI can be configured via the following environment variables: 359 360| Variable | Default | Description | 361|---------------------|----------------------------|-----------------------------------------------| 362| `POCKETENV_TOKEN` | _(none)_ | Override the session token (useful for CI/CD) | 363| `POCKETENV_API_URL` | `https://api.pocketenv.io` | Override the API base URL | 364| `POCKETENV_CF_URL` | `https://sbx.pocketenv.io` | Override the Cloudflare sandbox URL | 365| `POCKETENV_TTY_URL` | `https://api.pocketenv.io` | Override the TTY URL | 366 367**Example — using a token in CI:** 368 369```sh 370POCKETENV_TOKEN=<your-token> pocketenv ls 371``` 372 373## 📚 Documentation 374 375Full documentation is available at **[docs.pocketenv.io](https://docs.pocketenv.io)**. 376 377--- 378 379## 🤝 Contributing 380 381Contributions are welcome! Please read the [Contributing Guidelines](https://github.com/pocketenv-io/pocketenv/blob/main/CONTRIBUTING.md) before submitting a pull request. 382 383- **Bug reports & feature requests:** [Open an issue](https://github.com/pocketenv-io/pocketenv/issues/new) 384- **Community & feedback:** [Join our Discord](https://discord.gg/9ada4pFUFS) 385 386--- 387 388## 📄 License 389 390[Mozilla Public License 2.0](https://github.com/pocketenv-io/pocketenv/blob/main/LICENSE)