🍪 sokko

The Sokko CLI. Bring your local agent setup — secrets, memory, and config/workspace files — into a Sokko-hosted runtime in one command.

🍪 sokko migrate
   🥠 secrets   12 vars from .env
   🧠 memory    8 items
   📦 files     34 files · 1.2 MB
   ✅ your agent is fully baked

Install

npm i -g sokko
# or run without installing
npx sokko --help

Requires Node 18+.

Quick start

sokko login                 # paste your API key (or --key / $SOKKO_API_KEY)
sokko instances ls          # see your agents
sokko migrate               # pick an agent (or create one) and migrate your local dir

Auth & config

Credentials are stored at ~/.config/sokko/config.json (respects $XDG_CONFIG_HOME), mode 0600, shape { apiUrl, apiKey }.

• apiUrl defaults to https://sokko.ai; override with --api-url or $SOKKO_API_URL.
• apiKey from --key or $SOKKO_API_KEY overrides the stored value.

Every request sends Authorization: Bearer <apiKey> (and x-api-key).

Commands

| Command | What it does | | --- | --- | | sokko login | Validate and store an API key. | | sokko logout | Remove stored credentials. | | sokko whoami | Show the signed-in org and role. | | sokko instances ls | List your agents (name · runtime · status · size). | | sokko instances create | Create a new agent (interactive). | | sokko migrate | Migrate a local agent dir into an instance. |

sokko instances create

sokko instances create [--runtime <r>] [--name <n>] [--byok | --sokko-credits]
                       [--provider <p>] [--model <id>] [--api-key <k>]
                       [--region us|eu] [--memory] [--subscribe-memory monthly|annual] [--yes]

• Runtime: openclaw | hermes | paperclip | opensre.
• Name → an auto-derived, server-valid slug (^[a-z0-9]+(?:-[a-z0-9]+)*$).
• Credentials:
  • BYOK (--byok): requires --api-key and --provider (e.g. anthropic, openai, openrouter).
  • Sokko credits (--sokko-credits): Sokko-managed model — requires --model.
• Size is plan-derived (the server ignores any size in the body). The CLI shows it read-only after creation; change tiers in the dashboard.
• --memory enables the Sokko Memory add-on (paid; may prompt an upsell if not subscribed).

sokko migrate

sokko migrate [--instance <id>] [--runtime <r>] [--path <dir>] [--dry-run] [--yes]
              [--on-conflict skip|replace] [--only secrets,memory,files] [--create]
              [--subscribe-memory monthly|annual]

1. Resolve-or-create the target. Without --instance, pick from a list (plus ➕ Create a new agent…); --create or no agents → create flow.
2. Detect the local dir for the instance's runtime: openclaw → ~/.openclaw, hermes → ~/.hermes, paperclip → ~/.paperclip, opensre → ~/.opensre. Override with --path. (These default paths are best-guess — confirm against each runtime's own docs.)
3. Three lanes:
   • 🥠 secrets — the root .env → secrets import (default --on-conflict skip).
   • 🧠 memory — MEMORY.md / USER.md / IDENTITY.md and everything under memory/ → Sokko Memory.
   • 📦 files — everything else → a tar.gz bundle uploaded to object storage.
4. Ignore rules (files lane only): skips *.pem, *.key, id_rsa*, *token*, *secret*, .git/, node_modules/, caches, and oversized files. Honors a .sokkoignore (gitignore syntax) at the dir root. .env is never ignored.
5. --dry-run previews counts and the file manifest with zero network writes.

Memory upsell

If you have memory files but no Sokko Memory add-on, migrate pitches it rather than silently skipping. Enabling it is cost-incurring, so it always needs an explicit confirm (or --subscribe-memory monthly|annual) — never auto-accepted by --yes. If you're not an owner or have no base plan, the CLI prints a dashboard link and continues, reporting memory as skipped.

CI / non-interactive

Honors NO_COLOR and non-TTY, degrading to plain logs. For unattended runs pass --yes --instance <id> (and --key / $SOKKO_API_KEY).

Develop

pnpm install        # inside cli/
pnpm run build      # bundles to dist/cli.js
pnpm test           # vitest
pnpm typecheck      # tsc --noEmit
node dist/cli.js --help