Skip to content
CantelopBeta

Quick start

Create an agent App, try it locally, then deploy it. Cantelop handles routing, Sandbox lifecycle, and persistent storage.

Prerequisites#

  • Node.js 22 or newer and Bun
  • An API key for whichever agent SDK you pick below.
  • Docker with linux/amd64 build support, when deploying or using local container mode.
  • A Cantelop account, when you're ready to deploy. Local development needs no login.

Run it locally#

  1. Install the CLI#

    $ brew install stepandel/tap/cantelop

    Homebrew is recommended. The alternative installer supports macOS and Linux; follow its instructions to put cantelop on your PATH.

  2. Create a project#

    In an empty directory, choose the agent SDK your Session runtime will use:

    $ cantelop init -app hello -provider openai
$ npm install

    -app hello is the App slug this project deploys to. It need not exist yet, and init does not require a login. Four files are written, and none are overwritten:

    cantelop.json     app slug, entrypoints, environment declarations
src/api.ts        your public HTTP API
src/session.ts    your agent
package.json      the SDK and your agent SDK

  3. Add your provider key#

    cantelop dev reads a .env beside cantelop.json and passes it to both entrypoints:

    .env
    CODEX_API_KEY=sk-...

    Local only. Production values are set against the App and are never uploaded from your project. Names beginning with CANTELOP_ are reserved.

  4. Run it#

    Terminal
    $ cantelop dev
→ http://127.0.0.1:8787

    Then, in another terminal:

    Terminal
    $ curl -X POST http://127.0.0.1:8787/sessions \
    -H 'Content-Type: application/json' \
    -d '{"userId":"ada"}'
→ {"sessionId":"ses_..."}

    Copy the returned sessionId into the next request:

    Terminal
    $ curl -i -X POST http://127.0.0.1:8787/messages \
    -H 'Content-Type: application/json' \
    -d '{"userId":"ada","sessionId":"ses_...","prompt":"write hello.txt"}'
→ HTTP/1.1 202 Accepted

    202 Accepted confirms delivery was accepted, not that the agent has finished. The first message starts a Sandbox. Once the agent completes the task, look for hello.txt in .cantelop/dev/workspaces/.

    The starter opens one Workspace per userId. Reuse the returned sessionId to continue the same Session. In a production API, derive the user's identity from authentication rather than trusting the request body.

    Leave dev running: it rebuilds as you edit, and a failed build keeps the last good one serving. For Docker mode and its differences, see local development. To add live agent output, see SSE and WebSocket.

What you just ran#

  • The Edge API (src/api.ts) receives HTTP requests and dispatches messages.
  • The Session runtime (src/session.ts) runs your agent inside an isolated Sandbox and handles messages one at a time.
  • A Session keeps its identity when its Sandbox is released. A later message starts a fresh Sandbox; in-memory state must be restored by your agent.
  • A Workspace holds persistent files shared by its Sessions. This starter creates one per user. Add .cantelop/ to your .gitignore to exclude local data.

See architecture for the Agent model and runtime lifecycle.

Deploy it#

  1. Sign the CLI in#

    Terminal
    $ cantelop login

    Authorize the CLI in the browser tab it prints.

  2. Create the App#

    Terminal
    $ cantelop app create -slug hello
→ app_0123456789abcdef0123456789abcdef

    The slug must match app in cantelop.json — that is how a deploy finds its App, so generated IDs stay out of your source. It also names the App's public URL, https://hello.cantelop.dev. Choose your own available slug and update the manifest if hello is already taken.

  3. Set the production environment#

    Replace APP_ID below with the ID returned by app create. Set the secret for your selected provider; the command reads its value from stdin:

    $ cantelop app secret set APP_ID CODEX_API_KEY

    Paste the key, then press Enter and Ctrl-D. For Pi, use the credential name for your chosen provider. To set a non-secret variable:

    Terminal
    $ cantelop app env set APP_ID LOG_LEVEL=debug

    Secrets are write-only. Variables and secrets are shared by the API and new Sessions. Local .env values are never uploaded; see environments for required declarations and defaults.

  4. Deploy#

    Terminal
    $ cantelop doctor
$ cantelop deploy

    doctor checks your toolchain, project, and the configuration your manifest marks required, and exits non-zero if anything fails. deploy builds and uploads both components, then activates the release only when both succeed. Try the two requests above again with https://hello.cantelop.dev in place of the local address, using the new Session ID returned by the deployed App.

    cantelop deploy --dry-run runs the same build with no login and no release. Use it to catch build problems before deploying.

After deploying#

Open the console to inspect the App. See deployment for release behavior and the CLI reference for logs, Session inspection, and rollback.

You should see#

  • cantelop dev answering on http://127.0.0.1:8787.
  • A 202 Accepted response from /messages and hello.txt in the local Workspace once the agent finishes.
  • cantelop doctor reporting [pass] on every line.
  • cantelop deploy reporting both api and session_runtime succeeded.
  • Requests accepted by your deployed App at https://hello.cantelop.dev.
CLI reference →