Skip to main content
An agent talks to the platform the way you do: through the CLI (levelrail-cli) or the MCP server (levelrail-mcp). Everything it does goes through the normal API with the token you give it, so its access is exactly that token’s abilities, and every change lands in the audit log under the agent’s name.

​
Set up a project with init

Run this in the project root:
It detects the stack and writes three files: Detection order: Dockerfile, compose file, package.json (Next.js, NestJS, Express, Fastify, Vite), go.mod, Java (pom.xml, Gradle), Python (requirements.txt, pyproject.toml, Pipfile), then a plain index.html static site. Provider names match the build system’s own, so what init reports lines up with what a deploy will detect. Nothing from the project is executed. Flags:
  • --dry-run shows the plan and changes nothing.
  • --force overwrites files that already exist. Without it existing files are skipped, and the diff of what would change is shown.
  • --yes skips the confirmation prompt. A script without a terminal must pass --yes or --dry-run.
  • --json prints the plan and result as one JSON value.
  • --mode picks the tool exposure written to .mcp.json: agent-core (default), read-only, standard or full.
  • --dir, --api-url, --profile and --mcp-binary override the directory, the URL written into the files, the credentials profile and the MCP binary name.

​
Install the skill

The repository ships an agent skill that covers the deploy, wait, diagnose and roll back loop, so an agent follows the safe path without you pasting in instructions:
levelrail-cli init writes the same guidance into a project’s own AGENTS.md, filled in with that project’s app name and API URL.

​
Modes

The MCP server exposes a subset of its tools depending on the mode. Token counts are estimates of the tools/list payload the client loads into context. See Agent tooling audit for how the numbers are measured.

​
Tokens

Give each agent its own token so its actions are attributable and it can be revoked alone.
--preset takes observer, deployer or operator (see the table below); --abilities sets an explicit list instead. The --agent label is shown on the tokens page and recorded on every audit entry the token makes. Filter the audit log by it with audit-log --agent NAME or the agent chip on the audit log page. Settings > Agents in the dashboard shows the MCP connect snippet (copyable, per mode), lists agent tokens with their last used time, and has a “Create agent token” flow with the same three presets: The token is shown once, when it is created. Store it in your shell profile or secret manager as APP_API_TOKEN, not in the repo.

​
Read logs by level

The app Logs page (Search tab) shows a chip per level (error, warn, info, debug) with the number of loaded lines at that level, and a “Showing N of total” line. Each row has a gutter with an icon and the level word, so the level does not depend on color. The search loads the newest 1,000 matches; the total counts every match in the range. Agents get a capped excerpt of the same data from levelrail-cli logs query or the MCP query_logs tool, which filter by level, time window and text.

​
Dry run before changing anything

  • plan_change (MCP) previews a single mutating tool call without running it, and plan_apply previews a resource file. levelrail-cli apply --dry-run is the CLI form.
  • levelrail-cli apps preflight NAME checks DNS, ports, disk, the image and required env before a deploy.

​
Wait for a deploy

An agent should never assume a deploy worked. wait_for_deploy (MCP) or levelrail-cli apps wait NAME blocks until the deploy converges and reports success or the structured failure. On failure, read it with levelrail-cli apps deploys show NAME DEPLOY_ID, fix one thing, and retry. Roll back first if production is down.

​
Next steps

AI assistant integration

Run levelrail-mcp over stdio or HTTP and scope its token.

Agent tooling audit

Token cost per mode and the budget tests.
Last modified on October 12, 2026