Akter

Agents

An agent can run all of Akter Cloud: sign in, create an organization and an app, deploy it, call its actors, and remove everything again. It does that through Akter's hosted MCP server or through the akter CLI. Both are built from one list of operations, so they offer the same operations under the same names, take the same input and give the same answers.

Connect⁠

An agent app with a person at it, such as a chat or coding assistant, connects to the MCP server by its URL, https://mcp.akter.dev/mcp. The app opens a sign-in page: type your email, then the six-digit code Akter emails you, then approve. The agent then acts as you, with your roles in each organization, until the session ends or you sign it out (sessions_revoke, or akter sessions revoke). The session lasts 30 days. The other tools check your roles on every call, so a role change or removal applies to them at once; calls to actors carry your roles as they were at the agent's last token, so there it applies with the next token, within a minute.

A headless agent, such as a job in CI, sends an agent key as its bearer token instead: Authorization: Bearer ak_…. A person creates the key with the scopes, apps, spend cap and expiry the agent needs (akter api-keys create). A key with deploy scope and no apps list can create apps in its organization. A key limited to named apps can't, and apps_list shows it only those apps. The CLI reads the same key from AKTER_API_KEY.

Tools⁠

Every Cloud API operation is one tool, named <group>_<operation> after the akter <group> <operation> command: organizations_create, apps_create, builds_create, deploys_create, deploys_get, apps_delete and so on. A tool takes the command's input as one JSON object, its --input, and answers with exactly what the command prints with --json: the API's own answer, or its error body when the API refuses.

actors_list finds an app's actors: it answers with a page of them by actor name and key, optionally only one name (actor) and one environment (environment, prod by default), and with next while there is more. A page holds limit actors (500 at most, and by default) unless it is the last, which has no next, so call it again with after set to next until next is absent.

Calls to an app's actors are the actors_call, actors_query, actors_state, actors_watch, actors_create and actors_ensure tools, as akter actors <kind>. Each takes the app's url, as the command takes --url: a deployed app answers at https://<app>--<environment>--<organization>.akter.run, one label under akter.run. actors_watch takes count, as the command takes --count, and answers with that many replies, one JSON value per line.

An actor's files are the files_list, files_usage, files_download and files_upload tools, as akter files <kind>, with the same url. files_upload takes the file's bytes as base64 in content and answers with the receipt a command attaches at a path. files_download answers with the file's bytes as base64 chunks, one per line.

An actor's computers are the computers_list, computers_get, computers_logs, computers_pause, computers_resume, computers_stop and computers_delete tools, as akter computers <kind>, with the same url. Each but computers_list takes the computer's name as computer. computers_logs answers with a page of the computer's log, oldest first, each line with its seq; pass the last seq you saw as after to read on. There is no tool to make a computer or run a command on one: only the actor's own jobs do that. computers_delete removes the computer and its disk, so it asks the person to confirm, as below.

Each tool carries hints an agent app can show: read-only, destructive, idempotent and open-world (it reaches outside Akter, such as sending an email).

Confirmations⁠

Deleting an app, deleting a computer and other destructive tools need a person to confirm them, whatever the agent was told. The MCP server asks the person through the agent app (MCP elicitation) before it runs one, and refuses when the app can't ask. For a headless agent's key, Akter emails a code to the person who created the key, and the server asks for that code. An agent that already holds an approval token for the action passes it as the tool's approval argument, as the CLI takes --approval.

Changing the organization's spend cap, up or down (billing_setCap), and cancelling its paid plan (billing_cancel) need the same confirmation. They also need the organization's billing right, which only its owners hold and no agent key carries today, so a key asking for either gets 403 before any approval is asked for.

A first deploy⁠

  1. organizations_create with a name, unless you already belong to one.
  2. apps_create with the organization and the app's name. An agent key needs deploy scope and no apps list for this; otherwise a person creates the app.
  3. Bundle the app with akter deploy, or upload it yourself: builds_create answers with a presigned URL; send the bundle to it with an HTTP PUT, then builds_get until the build is Ready.
  4. deploys_create for the build, then deploys_get until its state is Live.
  5. Call the app's actors with actors_call and actors_query, with url set to https://<app>--<environment>--<organization>.akter.run.
  6. Clean up with apps_delete, which asks you to confirm.

When a tool fails⁠

A refusal from the API comes back as a tool error whose text is the API's error body, such as {"_tag":"NotFoundError","resource":"app"}. A failure the server finds itself, such as input that doesn't match the tool's schema or an API it can't reach, comes back as {"_tag":"CliExitError","code":…,"reason":…,"message":…} with the CLI's exit code for it. When the session behind a connection ends, the server answers 401 and the agent app signs in again.