Armalo Cloud
Open Cloud from the App.
Open in the App. Connect from Settings → Developer when you work in your own tools. The CLI is unpublished — do not install it from npm.
1. Open the App
The live path is the App. If you work from your own tools, connect once from Settings → Developer. MCP is the honest checkout path. The unpublished @armalo/cli package stays in this repo. Do not install that name from npm. npm 1.0.9 is a different product.
# App checkout only — not npm:
node packages/cli/bin/armalo.mjs --help
# Settings → Developer, or POST /mcp tool armalo_cloud_readiness2. Authenticate
Persist a scoped PAT to your local config (0600). The CLI uses the same auth resolution as every other armalo command: --key flag, then ARMALO_API_KEY env, then the config file.
armalo login
# or non-interactive:
armalo login --key armalo_pat_*** --base-url https://api.armalo.ai3. Subcommands
Every subcommand takes --json for machine-readable output. The CLI never prints bearer tokens, raw provider URLs, or internal hostnames.
armalo shell start [--region <two-letter>] [--json]
Start a new personal shell and print its connect endpoint.
$ armalo shell start
Sandbox sbx_8f2e9c0a1d3b (ready)
Region: us
Connect: https://shell.armalo.ai/v/us/sbx_8f2e9c0a1d3b
Expires: 2026-08-27T01:00:00Zarmalo shell list [--json]
List the shells your key currently has live, with status and region.
$ armalo shell list
SANDBOX ID STATUS REGION EXPIRES
sbx_8f2e9c0a1d3b ready us 2026-08-27T01:00:00Z
sbx_3a1f4d2b9c0e provisioning us 2026-08-27T00:30:00Zarmalo shell ssh <id> <sandbox-id> [--json]
Print the connect endpoint for an existing shell. Open it in a browser or your editor.
$ armalo shell ssh sbx_8f2e9c0a1d3b
https://shell.armalo.ai/v/us/sbx_8f2e9c0a1d3barmalo shell stop <id> <sandbox-id> [--json]
Stop a shell. Files stay with the prior id; resume with `armalo shell start` to bring the same shell back.
$ armalo shell stop sbx_8f2e9c0a1d3b
Stopped sbx_8f2e9c0a1d3b4. Tier requirements
The shell capability is enabled for Power User, Growth, Scale, and Enterprise tiers. Starter-tier PATs receive a 404 — the surface does not advertise itself to non-eligible tiers. The capability is the canonical authority; tier strings are reconciled to it on every request.
Existing customers with Starter workspaces keep using workspaces as before. The shell is opt-in; no forced migration.
5. Contract
The HTTP contract is documented in apps/server/src/dev-shell-routes.ts. The CLI is a thin wrapper — every command maps to exactly one of:
- POST /v1/dev/sandboxes — provision. Body: { "region": "<two-letter>" } (optional). Returns 201 with the sandbox object.
- GET /v1/dev/sandboxes — list. Returns { items: [...], total: <n> }.
- GET /v1/dev/sandboxes/:id — read one. Returns the sandbox object.
- DELETE /v1/dev/sandboxes/:id — stop. Returns 200 { ok: true }.
Every response is the public DevSandbox projection. The shape is frozen; substrate details are intentionally omitted from the wire.
Questions?
What tier do I need?+
Power User, Growth, Scale, or Enterprise. A Starter-only PAT receives a 404 from the route — intentional, so the surface does not advertise to ineligible tiers.
How is the contract endpoint derived?+
It is the only opaque identifier ever shown. The hostname (shell.armalo.ai) is owned by Armalo. The path segment is the shell id; the region is one of the small set we operate in. Provider URLs and internal hostnames never appear in the response.
Can I open multiple shells?+
Yes, up to your tier's concurrent shell ceiling. Power User is single-shell; Growth raises the cap; Scale and Enterprise negotiate further. The route returns 429 when you exceed the cap.
What happens to a stopped shell?+
Stop frees the compute but keeps your files. A later `armalo shell start` can return the same id; a fresh start returns a new id with no retained state.
Looking for a workspace instead of a shell? Starter, Growth, and Scale still ship the workspace surface alongside the shell. One subscription, both primitives.