> ## Documentation Index > Fetch the complete documentation index at: https://docs.levelrail.com/llms.txt > Use this file to discover all available pages before exploring further. # Working with AI agents > Connect an AI coding agent to your instance, scope its token, and give it the instructions it needs to deploy safely. 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: ```bash theme={"dark"} levelrail-cli init ``` It detects the stack and writes three files: | File | What it is | | - | - | | `app.yaml` | The app spec, validated with the same parser the control plane uses before it is written. | | `AGENTS.md` | Instructions for an agent: deploy, wait, read a failure, roll back, set env and secrets safely. Uses the CLI name you ran and your API URL when the CLI knows it. | | `.mcp.json` | A stdio MCP server entry. The token is an env var reference (`${APP_API_TOKEN}`), never a value. | 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: ```bash theme={"dark"} npx skills add glincker/levelrail ``` `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. | Mode | Tools | Estimated tokens | Use it for | | - | - | - | - | | `agent-core` (a tool profile, `--tool-profile agent-core`) | 15 | about 2,600 | Shipping and debugging one app. The default for `init`. | | `read-only` | 118 | about 46,200 | Observers that must not change anything. | | `standard` | 146 | about 61,200 | Read and mutating tools, no destructive ones. | | `full` | 156 | about 66,700 | Every tool, including destructive ones. | See [Agent tooling audit](/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. ```bash theme={"dark"} levelrail-cli tokens create --name ci-agent --preset deployer --agent "Claude Code" ``` `--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: | Preset | Abilities | Can do | | - | - | - | | Read-only observer | `read` | Look at apps, logs, metrics and deploys. | | Deployer | `read`, `deploy` | Also trigger deploys and rollbacks. | | Full operator | `read`, `read:sensitive`, `write`, `write:sensitive`, `deploy` | Also change config, env vars, domains and secrets. Never `root`. | 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 Run `levelrail-mcp` over stdio or HTTP and scope its token. Token cost per mode and the budget tests. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.