Copy for LLM

Quick start

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

SDK 1.0 is the only supported SDK.

Prerequisites#

• Node.js 22 or newer and Bun 1.3.10 for native local development. Docker mode (cantelop dev --container) can be used instead of Bun.
• Cantelop CLI 0.15.2 or newer. Check with cantelop version after installing.
• An API key for whichever agent SDK you pick below.
• A backend of your own to call the App from. Any Node.js server works; the steps below use a one-file script.
• 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#

   The CLI creates local agent projects, runs them, and uploads builds when you deploy. Homebrew manages installation and removal. The alternative script downloads a release from Cantelop’s stepandel/homebrew-tap GitHub repository, verifies its SHA-256 checksum, and installs cantelop in ~/.local/bin (replacing an existing copy there). Review the script before running it. The command below disables automatic shell-profile edits; add ~/.local/bin to your PATH yourself if needed.

   Homebrewcurl

   $ brew install stepandel/tap/cantelop
   

   Homebrew is recommended. The alternative installer supports macOS and Linux; see removal instructions to undo the installation.

2. Create a project#

   In an empty directory, choose the agent SDK your Session runtime will use, then install the stable Cantelop SDK 1.0 package:

   OpenAIClaudePi

   $ cantelop init -app hello -provider openai
   $ npm install @cantelop/sdk
   

   -app hello is the App name 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      points the CLI at your App definition
   src/cantelop.ts    the App: name, runtime, environment declarations
   src/agent.ts       your agent, run inside each Session's Sandbox
   package.json       your agent SDK; the install adds the Cantelop SDK
   

   The manifest only names the definition module:

   cantelop.json

   {
     "schema_version": 3,
     "definition": "src/cantelop.ts"
   }
   

   Everything else about the App is declared in code. Starters generated by CLI 0.15.2 omit the inline message type cantelop.app<{ prompt: string }>; add it before running dev to avoid a declaration-generation error. Later CLI releases generate it. For the Claude starter:

   src/cantelop.ts

   import { CantelopClient } from "@cantelop/sdk";
   import { receive } from "./agent.js";
   
   const cantelop = new CantelopClient();
   export const agent = cantelop.app<{ prompt: string }>({
     name: "hello",
     runtime: { receive },
     environment: {
       ANTHROPIC_API_KEY: { secret: true, required: true },
     },
   });
   

   There is no HTTP API to write. Cantelop generates the App's Edge Worker, and your own backend reaches the App through this same agent export.

3. Add your provider key#

   cantelop dev reads a .env beside cantelop.json and passes the values your App declares to its Sessions:

   OpenAIClaudePi

   .env

   CODEX_API_KEY=sk-...
   

   The Pi starter declares no environment. Add the credential your provider needs to environment in src/cantelop.ts, for example ANTHROPIC_API_KEY: { secret: true, required: true }.

   Keep .env out of version control. Local development does not upload it; deploy --env-file .env explicitly imports declared production values. Names beginning with CANTELOP_ are reserved.

4. Run it#

   Terminal

   $ cantelop dev
   → Cantelop App running at http://127.0.0.1:8787 (native mode)
   

   dev builds the App, records a local credential in the SDK's local profile, and writes a compiled backend client to .cantelop/client/. That client keeps your App's exports but none of its Sandbox code, so a backend can import it without loading your agent SDK.

   Leave dev running and, in a second terminal, send the agent a message from a small backend script:

   try.mjs

   import { agent } from "./.cantelop/client/client.mjs";
   
   const session = agent.workspace({ slug: "ada" }).session();
   const message = await session.dispatch({ prompt: "write hello.txt" });
   console.log(session.id, message.id, message.state);
   

   Terminal

   $ CANTELOP_PROFILE=local node try.mjs
   → ses_... msg_... accepted
   

   accepted confirms durable admission, not that the agent has finished. The first message provisions the ada Workspace and starts a Sandbox. Once the agent completes the task, look for hello.txt under .cantelop/dev/hello/workspaces/.

   Pass the printed Session ID as session({ id }) to continue the same Session, or read its output with session.stream(). The integration credential authorizes every Workspace in the App, so it stays on your backend: authenticate your own users and choose their Workspace there.

   dev rebuilds as you edit, and a failed build keeps the last good one serving. For Docker mode and its differences, see local development. To relay live agent output, see streaming output.

What you just ran#

• The App definition (src/cantelop.ts) declares the App's name, runtime, environment, and optional webhooks with cantelop.app(...).
• The Session runtime (src/agent.ts) runs your agent inside an isolated Sandbox. See Session runtime.
• The generated Edge Worker accepts your backend's commands at /commands/{command}, one path per SDK call. You never write it; see ingress.
• 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. Select one per user with agent.workspace({ slug }). Add .cantelop/ to your .gitignore to exclude local data and the compiled client.

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. Deploy#

   Terminal

   $ cantelop deploy --create-app --env-file .env
   

   deploy builds the generated Edge Worker and Session runtime image, creates the hello App if it does not exist, and imports the names your App declares in environment from .env: secrets as secrets, the rest as variables. Undeclared entries are ignored. It then uploads both components and activates the release only when both succeed.

   The App name in src/cantelop.ts also names its public URL, https://hello.cantelop.dev. Choose your own available name if hello is already taken. Later deploys need only cantelop deploy; see environments for changing values without deploying.

   cantelop deploy --dry-run runs the same build with no login and no release. cantelop doctor checks your toolchain, project, and required configuration once the App exists.

3. Call it from your backend#

   Deploying records the App's integration credential in the SDK's default profile, so the same script reaches the deployed App:

   Terminal

   $ CANTELOP_PROFILE=default node try.mjs
   → ses_... msg_... accepted
   

   A backend hosted elsewhere cannot read that profile. Give it the credential through the host's secret store instead:

   Terminal

   $ cantelop app credentials
   

   It prints CANTELOP_APP_SLUG and CANTELOP_INTEGRATION_TOKEN as dotenv. Keep the token on the backend, never in browser code.

   Deploy the backend and App from the same source; see deploy your backend with the App.

After deploying#

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

You should see#

CLI reference →