# Deployment.io > Deployment.io turns an outcome you describe into shipped software — its AI agents write the code, test it, and deploy it to your own cloud. Deployment.io turns an outcome into a deployment. You describe what you want shipped; our AI agents plan the work, write the code across your repos, test every change before you review it, and ship it to your cloud. You approve what reaches production. Prefer to drive it yourself? Point your own coding agent at Deployment.io over MCP. Either way, everything runs in your own cloud and nothing reaches production without your sign-off. ## Two Ways to Use Deployment.io - **Self-serve**: Describe an outcome and our agents ship it, or connect your own coding agent (Claude Code, Cursor, Windsurf, Copilot, OpenAI Codex, Gemini CLI, and other SKILL.md-compliant agents) over MCP. You operate the platform. Metered by jobs. - **Managed**: Our team operates Deployment.io for you — done-for-you engineering that turns a backlog of outcomes into deployments on your cloud. Custom annual retainer. ## What Makes Deployment.io Different - **More than code generation**: Not just code generation. Our planning agent reads your repos and architecture, writes a spec, and decomposes an outcome into ordered work across the right repos. Agents then build, verify, and ship. - **Verified before it ships**: The agent runs your build and tests on every change and only marks a Task done when they pass — nothing reaches production unvalidated. - **Your cloud, your data**: Code, secrets, build artifacts, and runtime traffic never leave your own cloud account. We connect via a scoped role you control — revoke it and we lose access instantly. - **Open-source runner**: The runner that touches your infrastructure is open source. Audit it, fork it, run your own build. - **Open-source skill**: A SKILL.md-compliant skill (MIT, github.com/deployment-io/skills) teaches your agent the deploy playbook. Pairs with the MCP server. - **Approval gates by default**: Production deploys pause for human sign-off — from Slack or the dashboard. - **RBAC for humans and agents**: Scope what each teammate — and each MCP token — can deploy, read, or approve. ## How It Works 1. **Describe an outcome** — a feature, a migration, a fix. 2. **The planning agent plans it** — reads your repos and architecture, writes a spec, and decomposes it into ordered work across the right repos. 3. **Agents build it** in sandboxed environments with scoped, least-privilege access to your cloud. 4. **Each change is verified against your build and tests** before it ships. 5. **You approve production** — deploys to your cloud as static sites, web services, or full environments. Nothing ships without your sign-off. Driving it yourself with your own agent over MCP? The open-source skill teaches the deploy playbook; native MCP tools give the agent the actions to execute. ## What Deployment.io Can Ship 1. **Static Sites**: React, Next.js, Vue, Astro, and other static frameworks — deployed to S3 + CloudFront with HTTPS, cache invalidation, and rollbacks. 2. **Web Services**: Go, Node.js, Python, Ruby, and Rust services — deployed to ECS with auto-scaling, health checks, and zero-downtime rollouts. 3. **Multiple Environments**: Dev, staging, and production — each in its own AWS account if you want. Switch between them with a single MCP call. ## Platform Features - AI planning + multi-repo Tasks: describe an outcome, get a spec and ordered work across repos - Build/test self-verification on every change before anything ships - Native MCP tool surface (`deploy_static_site`, `deploy_web_service`, `get_deployment_logs`, `get_approval_status`, `list_environments`, `create_environment`, `edit_environment`, `list_runners`, `get_job_status`) - Zero-config auto-detection: Dockerfile, exposed port, health-check path, build command, and output directory read straight from the repo - Human approval gates with Slack + dashboard sign-off - Build & runtime logs with regex search and time-range filtering from CloudWatch - RBAC for humans and MCP tokens - Auto-deploy on git push (wire a branch to an environment once) - Custom domains, HTTPS, Slack alerts - Encrypted secrets per environment (env vars + secret files, scoped per environment) ## MCP Tools Coding agents interact with Deployment.io through these MCP tools: - `deploy_static_site` — Deploy static sites (React, Next.js, Vue, Astro, Vite) to S3/CloudFront. Auto-detects build command and output directory. - `deploy_web_service` — Deploy Dockerized backend services to ECS. Auto-detects port from Dockerfile EXPOSE and health-check path. - `list_environments` — List all environments with IDs, names, regions, and dashboard links. - `create_environment` — Create a new environment (Production / Staging / Development). - `edit_environment` — Rename an existing environment. - `list_runners` — List available infrastructure runners (shared cloud or custom AWS). - `get_deployment_logs` — Fetch logs with time-range filtering and regex search. Up to 500 lines per request. - `get_job_status` — Check the status of an async deployment job. - `get_approval_status` — Check the status of a pending production-deploy approval. ## The Deployment.io Skill A SKILL.md-compliant bundle that teaches your coding agent how to deploy on Deployment.io. With the skill, the runbook (framework→publish_directory mapping, is_spa detection, port discovery, health-check routes, git pre-flight, approval flow) loads automatically. - Source: github.com/deployment-io/skills (MIT, semver) - Works with: Claude Code, Claude Desktop, Cursor, OpenAI Codex CLI, Gemini CLI, and 25+ other SKILL.md-compliant agents - Install: clone the repo and copy `skills/deployment-io/` into your agent's skills directory ## Documentation Structure - `/docs/introduction/` — What Deployment.io is and why it exists - `/docs/introduction/glossary/` — Definitions of core terms (outcome, Task, Step, job, runner, environment, MCP server, skill) - `/docs/coding-agents/` — MCP configuration, available tools, and the Deployment.io skill - `/docs/runner-installation/` — Setting up the runner on AWS - `/docs/infrastructure/` — AWS infrastructure configuration - `/docs/dashboard/` — Using the dashboard - `/docs/role-based-access-controls/` — Team permissions and RBAC - `/docs/guides/` — Step-by-step tutorials and how-to guides - `/blog/` — Articles on AI-driven deployments, platform updates, and guides ## Key URLs - Website: https://deployment.io - Managed service: https://deployment.io/managed/ - Documentation: https://deployment.io/docs/ - Pricing: https://deployment.io/pricing/ - Security: https://deployment.io/security/ - Blog: https://deployment.io/blog/ - Sign Up: https://app.deployment.io/signup - Dashboard: https://app.deployment.io - Skill repo: https://github.com/deployment-io/skills ## Comparisons How Deployment.io compares to deployment platforms — it adds AI planning, multi-repo Tasks, build/test self-verification, and deploys into your own cloud: - Deployment.io vs. Vercel: https://deployment.io/blog/deployment-io-vs-vercel-4-reasons-why-you-should-consider-deployment-io/ - Deployment.io vs. Netlify: https://deployment.io/blog/deployment-io-vs-netlify-5-compelling-reasons-to-switch-to-deployment-io/ - Deployment.io vs. Render: https://deployment.io/blog/deployment-io-vs-render-4-reasons-to-switch-from-render/ - One MCP call vs. fifty (why an AI agent needs a platform, not a toolchain): https://deployment.io/blog/one-mcp-call-vs-fifty-platform-abstraction-for-ai-agents/ ## Pricing Self-serve is metered by jobs; Managed is a custom retainer. - **Free**: 10 jobs/month, 1 user — includes Tasks and planning - **Team**: from $99/month (200 jobs); $499/month (1,000 jobs) - **Managed**: custom — our team operates Deployment.io for you, turning outcomes into deployments on your cloud - **First Outcome Sprint**: $7,500 fixed — one outcome planned, built, verified, and shipped to your cloud in two weeks, with half held back until it's live and verified. The entry point into Managed. A "job" is any AI, CI/CD, or infrastructure task that runs on your cloud or ours — build creation, preview generation, deployment, custom-domain setup, response-header configuration, or AI-driven log debugging. ## Security - Runs in your own cloud account — code, secrets, and traffic never leave it - Scoped role-based access; revoke to cut off access instantly - Encrypted env vars and secret files at rest - Open-source runner you can audit or fork - Sandboxed agent execution with least-privilege access - Role-based access control (RBAC) for humans and MCP tokens - Production deploys require human approval by default - Audit logs for all deployment activity ## Contact - Email: hello@deployment.io - Support: Priority email support for Team and Managed plans ## Integration Deployment.io complements existing CI/CD pipelines (GitHub Actions, Jenkins, etc.) and integrates natively with AWS — one-click environments and multi-account support. --- # Full Documentation # What is Deployment.io? --- Deployment.io takes an outcome you describe all the way to shipped software. You describe an outcome — a feature, a migration, a fix — and our AI agents plan the work, write the code across your repos, test every change before you review it, and ship it to your cloud. You approve what reaches production. Here's how an outcome becomes a deployment: 1. **Plan**: Our planning agent reads your repos and architecture, writes a spec, and breaks the outcome into ordered work across the right repos. 2. **Build**: Agents write the code in sandboxed environments with least-privilege, scoped access to your cloud. 3. **Verify**: The agent runs your build and tests in its sandbox and only marks a Task done when they pass — so it's validated before it ships and you review working software, not a diff you hope works. 4. **Ship**: Changes deploy to your cloud as static sites, web services, or on-demand environments. Nothing reaches production without your approval. 5. **Your cloud, your control**: All infrastructure runs in your own cloud account through a scoped role you can revoke anytime. ## Bring your own coding agent Prefer to drive the work yourself? Coding agents like Claude Code, Cursor, Windsurf, Copilot, OpenAI Codex, Gemini CLI, and Antigravity connect to Deployment.io through its MCP server. Once connected, your agent can spin up environments and deploy static sites and web services — into your own cloud, with the same approval gates. See [Coding Agents](/docs/coding-agents/mcp-configuration/) to get set up. --- # Why Deployment.io? --- Coding agents made writing code fast. Turning an outcome into shipped software didn't keep up — planning the work, coordinating changes across repos, standing up infrastructure, verifying everything works, and rolling out to production safely is still manual. That work in between is left to you. Deployment.io runs that whole system end to end: 1. **Start from an outcome**: Describe what you want shipped, and our planning agent turns it into a spec and ordered work across the right repos — instead of hand-holding every change. 2. **No DevOps expertise required**: Agents handle infrastructure, builds, and rollout — no need to learn cloud internals, Terraform, or CI/CD pipelines. 3. **Verified before it ships**: Every change is validated against your build and tests first, so you review working software instead of hoping it works. 4. **Safe by design**: Agents run in sandboxes with scoped, least-privilege access, and nothing reaches production without your approval. 5. **Your cloud, your control**: Everything runs in your own cloud account through a role you can revoke anytime. Deployment.io orchestrates the work; your resources stay yours. --- # Glossary --- Plain-language definitions of the core Deployment.io terms — outcome, Task, job, runner, environment, MCP server, and more. ### Approval gate A checkpoint that pauses a production deployment until a human signs off — from Slack or the dashboard. Approval gates are on by default, so nothing reaches production without your go-ahead. ### Environment An isolated deployment target — for example dev, staging, or production — each optionally in its own cloud account. Agents deploy to a specific environment, and you can switch between them with a single MCP call. ### First Outcome Sprint A fixed-price ($7,500), two-week entry engagement into Managed: one real outcome planned, built, verified, and shipped to your cloud, with half the price held back until it's live and verified. ### Job The billing unit. A job is any AI, CI/CD, or infrastructure task that runs on your cloud or ours — a Task, a deploy, a log fetch, a custom-domain setup, a response-header change, or AI-driven log debugging. A Task counts as one job. ### Managed The done-for-you tier: the Deployment.io team operates the platform for you, turning a backlog of outcomes into deployments on your cloud. Priced as a custom retainer. (On the self-serve tiers — Free and Team — you operate the platform yourself.) ### MCP server Deployment.io's native Model Context Protocol surface. It gives coding agents real deploy actions to call — `deploy_static_site`, `deploy_web_service`, `get_deployment_logs`, `get_approval_status`, and more — so the agent executes actual deployments, not chat. ### Outcome A result you want shipped — a feature, a migration, a fix — rather than a single edit or ticket. You describe an outcome, and the planning agent turns it into ordered work across the right repos. ### Planning agent The agent that reads your repos and architecture, writes a spec, and decomposes an outcome into ordered Tasks across the right repos. ### Runner The open-source component that runs inside your own cloud and does the work that touches your infrastructure — checking out code, building, and deploying. Access to your cloud never leaves your environment, and you can audit or fork the runner. ### Self-serve Using Deployment.io as a platform you operate yourself (the Free and Team plans): describe an outcome and the agents ship it, or point your own coding agent at the MCP server. Contrast with Managed, where our team operates it for you. ### Self-verification The step where an agent runs your build and tests in its own sandbox and only marks a Task done when they pass — so you review changes that already work instead of diffs you hope work. ### Skill An open-source, SKILL.md-compliant bundle (MIT) that teaches your coding agent Deployment.io's deploy playbook — framework-to-output mappings, port and health-check discovery, and the approval flow. It pairs with the MCP server. ### Step An optional sub-unit of work within a Task. Multi-Step Tasks break a Task into ordered Steps, and each Step counts as one job. Most Tasks use zero user-defined Steps, so they're a single job. ### Task The unit of execution. The planning agent decomposes an outcome into one or more Tasks across the right repos; each Task runs in an isolated, sandboxed container, writes and commits code, and is verified before it's marked done. One Task is one job, and Tasks can declare dependencies so multi-repo changes ship in the right order. --- # LLM Providers --- Deployment.io's agents — the ones that run Tasks and Assistant sessions — call an LLM on **your** vendor account. You configure a provider once per organization, and every agent run from then on uses it. Usage is billed by the vendor directly; Deployment.io doesn't resell tokens. ## Supported providers | Provider | Credential | Used by | | ---------------------------------------------- | --------------------------- | ----------------------------------- | | [Anthropic](/docs/ai-providers/anthropic/) | Anthropic API key | The Claude Code and opencode agents | | [OpenAI](/docs/ai-providers/openai/) | OpenAI API key | The Codex and opencode agents | | [AWS Bedrock](/docs/ai-providers/aws-bedrock/) | None — your own AWS account | The Claude Code and opencode agents | Each provider is configured independently — saving one never touches another. You only need the provider for the agent you actually use. The per-provider pages cover setup and provider-specific troubleshooting; everything on this page applies to all of them. > **Tasks are blocked until a provider is configured.** Creating a Task requires the organization to have at least one usable agent credential. If you haven't added one, Task creation is refused. ## Where to find it **Organization Settings → Agents → LLM Providers** (`https://app.deployment.io/org-settings/agents`). The page shows one card per provider. API-key providers have their own input and Save button; AWS Bedrock is enabled with a single click, since it stores no credential. --- ## How credentials are stored - **Encrypted at rest.** Keys are encrypted with AES-GCM before they're written to the database. They are never stored in plaintext. - **Never re-displayed.** After you save, the dashboard and the API only ever return a masked form of the key. - **Decrypted only at run time.** When an agent job starts, the key is decrypted and passed to the sandboxed agent container running on your runner. ## Rotating a key Once a key is saved, its section shows it masked — the first few and last few characters only, with the middle redacted. The plaintext is never returned to the browser again. To rotate: 1. Click **Replace** next to the masked key. 2. Paste the new key into the **New API key** field. 3. Click the section's **Save** button. The existing key stays active until the new one is saved, so there's no window where agents are left without a credential. Click **Cancel** to back out without changing anything. To stop using a provider entirely, click **Remove** on its card. If no other provider is configured afterwards, Task creation is blocked until one is. ## Validation Every provider's key field applies the same sanity checks before anything is saved: | Condition | Result | | ------------------------ | ------------------------------------------------------------------- | | Empty | "API key is required" — the Save button stays disabled | | Fewer than 20 characters | "API key looks too short — double-check the value you pasted" | | More than 500 characters | Rejected — check that you pasted only the key, not surrounding text | These catch truncated or mis-pasted values. They don't verify the key against the vendor, so a well-formed but revoked key will save successfully and fail later at run time. ## Troubleshooting - **You can't create a Task at all** — no agent credential is configured for the organization. Add one for the provider your agent uses. - **You changed a key but runs still fail** — confirm you saved the section you meant to. Providers are stored independently, and an agent never falls back to another provider's key. For provider-specific issues — key format, revoked keys, spend limits, Bedrock model access — see the [Anthropic](/docs/ai-providers/anthropic/), [OpenAI](/docs/ai-providers/openai/), and [AWS Bedrock](/docs/ai-providers/aws-bedrock/) pages. --- Connecting your own coding agent over MCP? It uses its own credentials, not these — see [MCP Configuration](/docs/coding-agents/mcp-configuration/). --- # Anthropic --- The Anthropic provider authenticates the **Claude Code and opencode agents** with an Anthropic API key from your own Anthropic account. Usage is billed by Anthropic directly. If you're new to configuring providers, start with the [LLM Providers](/docs/ai-providers/llm-providers/) overview — it covers where the settings live, how keys are stored, and how rotation works for every provider. ## Adding an Anthropic key 1. Create a key at platform.claude.com/settings/keys. Copy it — Anthropic only shows it once. 2. In the dashboard, go to **Organization Settings → Agents → LLM Providers**. 3. On the **Anthropic Direct** card, paste the key into the **API key** field. It starts with `sk-ant-api03-`. 4. Optionally click the eye icon to unmask the field and confirm you pasted the whole key. 5. Click **Save**. You'll get an "Anthropic Direct saved" confirmation, and the field collapses to a masked display. ## Rotating Click **Replace** next to the masked key, paste the new one, and save. The existing key stays active until the new one is saved — see [Rotating a key](/docs/ai-providers/llm-providers/#rotating-a-key). **Remove** deletes the credential entirely. ## Troubleshooting - **"API key looks too short"** — you probably copied a partial value. Anthropic console keys are around 100 characters. Re-copy the whole key. - **A Task fails with an authentication error** — the saved key may have been revoked or may have hit a spend limit. Check the key's status in the Anthropic console, then rotate it using **Replace**. - **Runs fail after switching agents** — the Anthropic key serves the Claude Code and opencode agents. If you've switched to the Codex agent, configure [OpenAI](/docs/ai-providers/openai/) as well; agents never fall back to another provider's key. --- # OpenAI --- The OpenAI provider authenticates the **Codex agent** — and the **opencode agent** when it runs OpenAI models — with an OpenAI API key from your own OpenAI account. Usage is billed by OpenAI directly. If you're new to configuring providers, start with the [LLM Providers](/docs/ai-providers/llm-providers/) overview — it covers where the settings live, how keys are stored, and how rotation works for every provider. ## Adding an OpenAI key 1. Create a key at platform.openai.com/api-keys. 2. In the dashboard, go to **Organization Settings → Agents → LLM Providers**. 3. On the **OpenAI Direct** card, paste the key into the **API key** field. It starts with `sk-`. 4. Click **Save**. You'll get an "OpenAI Direct saved" confirmation, and the field collapses to a masked display. ## Rotating Click **Replace** next to the masked key, paste the new one, and save. The existing key stays active until the new one is saved — see [Rotating a key](/docs/ai-providers/llm-providers/#rotating-a-key). **Remove** deletes the credential entirely. ## Troubleshooting - **"API key looks too short"** — you probably copied a partial value. Re-copy the whole key from the OpenAI console. - **A Task fails with an authentication error** — the saved key may have been revoked or may have hit a spend limit. Check the key's status in the OpenAI console, then rotate it using **Replace**. - **Runs fail after switching agents** — the OpenAI key serves the Codex agent, and opencode on OpenAI models. If you've switched to the Claude Code agent or an Anthropic model, configure [Anthropic](/docs/ai-providers/anthropic/) as well; agents never fall back to another provider's key. --- # AWS Bedrock --- The AWS Bedrock provider routes agent LLM calls through **Amazon Bedrock in your own AWS account** instead of a vendor API key. ## Why Bedrock - **No API key to manage.** There is nothing to paste and no secret stored on the Deployment.io side — selecting the provider is the configuration. - **Billing through AWS.** Model usage lands on your existing AWS bill, alongside the infrastructure your runner already manages. - **Your account boundary.** Prompts and completions flow through Bedrock in your own AWS account and region — they never transit a vendor account you don't control. ## Enabling Bedrock 1. In the dashboard, go to **Organization Settings → Agents → LLM Providers**. 2. On the **AWS Bedrock** card, click **Enable AWS Bedrock**. That's the whole setup — there is no credential to enter. When an agent job starts, your runner issues short-lived, narrowly scoped AWS credentials to the sandboxed agent container, and the agent calls models served by Bedrock in your runner's region. There are no long-lived keys to rotate or leak. ## Requirements | Requirement | Why | | ----------------------------- | ----------------------------------------------------------------------------------- | | Your own AWS runner | The runner issues the scoped credentials the agent uses. | | Bedrock model access | Claude models must be enabled in Bedrock in your runner's region. | | Claude Code or opencode agent | Bedrock serves the Claude Code and opencode agents; the Codex agent is OpenAI-only. | ## Disabling Click **Remove** on the AWS Bedrock card. If no other provider is configured afterwards, Task creation is blocked until one is. ## Troubleshooting - **A Task fails with an access or authorization error** — Claude model access is probably not enabled in Bedrock in your runner's region. Enable it in the AWS console under **Bedrock → Model access** and re-run. - **A model you expected isn't available** — model availability on Bedrock can trail the direct Anthropic API, and varies by region. A newly released model may take time to appear in your runner's region. --- # What is a Session? --- A **session** is a conversation with an agent that can read your code. Ask it how something works, where a behaviour lives, or what a change would involve — and when you decide you want that change made, it writes up a **spec** you can hand straight to a [Task](/docs/tasks/what-is-a-task/). Sessions live under **Assistant** in the sidebar. ## Session or Task? | | **Session** | **Task** | | --------------- | -------------------- | --------------------------------- | | Use it to | Decide _what_ to do | Get it _done_ | | Interaction | Back-and-forth chat | Fire and forget | | Your code | Read only | Writes code, opens a pull request | | You end up with | Answers, plus a spec | A pull request to review | Start a session when you're still working out what needs to change — _"how does auth work here?"_, _"what would it take to add SSO?"_. Create a Task when you already know. One button connects them: **Create task** turns the session's spec into a Task, carrying everything across. ## It won't touch your code A session only reads. It doesn't edit files, run tests, or push anything, and the copy it works from disappears when the session ends. Ask it to run your test suite and it will decline — and usually add the check to the spec instead, so it gets run later when the Task executes. > With Claude Code this is enforced: the agent physically can't do anything but read and search. Codex sessions rely on the agent following instructions. Either way nothing reaches your repository, but pick Claude Code if you want the stronger guarantee. ## Before you start Four things, all checked for you when you open **New session** — anything missing is named on screen with a link to fix it. | You need | Why | | --------------------------------- | ------------------------------------------------------------------------------------------------------------ | | A runner in your AWS account | Sessions run on your own infrastructure. See [Runner Installation](/docs/runner-installation/architecture/). | | It to be online | An offline runner can't pick up the work. | | An LLM key for the agent you pick | Anthropic for Claude Code, OpenAI for Codex. See [LLM Providers](/docs/ai-providers/llm-providers/). | | At least one connected repository | The agent needs something to read. See [Adding a Repository](/docs/dashboard/adding-a-repository/). | Usage is billed by Anthropic or OpenAI on the key you configured. --- # Running a Session --- ## Start one Go to **Assistant** and click **New session**. Give it a **title**, pick the **repositories** you want the agent to look at and the **branch** for each, then choose the **agent** and **model** it should think with. Claude Code on Opus 4.8 is a good default; Codex is there if you prefer it. Click **Start session**. Your first question can take a few minutes to come back while the agent gets set up. After that, replies are quick. ## Ask it things The conversation sits in the middle, your other sessions on the left, and the **spec** on the right once there is one. Replies stream in as they're written. When the agent goes off to look through your code, the steps it takes collapse into a summary you can expand if you're curious — the answer itself is always shown in full. You can only send one message at a time: while the agent is working, sending is paused until it's finished. You can keep typing meanwhile. Close the tab whenever you like. Come back and the conversation is still there. ## Sessions end on their own A session closes after **30 minutes without activity**, or **4 hours** in total — whichever comes first. Turning the spec into a Task also closes it. When that happens the conversation becomes read-only. Everything stays readable, and any spec it produced can still be turned into a Task. Sessions can't be reopened, so start a new one if you need to keep going. > Sessions and Tasks draw on the same LLM account, and a session holds its place for as long as it's open. Convert it or leave it once you have what you need. ## If something goes wrong **The agent stops mid-conversation.** You'll see a message explaining why — usually credits, a rate limit, or an authentication problem with your LLM key. The session ends and you'll need to start a new one once it's sorted. **A message won't send.** Your text is kept, so just try again. **Replies stop appearing.** The connection recovers on its own and catches up — no need to reload. --- # From Spec to Task --- The point of a session isn't the conversation — it's the **spec** that comes out of it. Once you've said you want something changed, the agent writes one up on the right and keeps it current as you talk. ## When a spec appears Only when you ask for a change. Questions get answers and nothing more — asking _"how does session expiry work?"_ won't produce a spec. Say _"let's make sessions expire after an hour"_ and one starts taking shape. It covers the goal, what "done" looks like, anything the agent assumed, what it's deliberately leaving out, and how big a job it thinks this is. At the top you'll see whether the agent considers it **vague**, **partial** or **ready** — useful as a nudge, though you can go ahead whenever you're happy with it. **To change the spec, talk to the agent.** Tell it what it's got wrong or what's missing and it rewrites it. There's no edit box, deliberately — the spec and the conversation stay in step. ## Turning it into a Task Click **Create task** under the spec. You'll see the goal and criteria one more time, and choose the **model** that should do the work. The default is picked for you based on how big the agent thinks the job is — bigger jobs get a more capable model. You can switch to a different agent here too, and change it again later. Click **Create Task**. ## What happens next **The Task goes to your backlog — it doesn't start running.** You'll land on the Tasks board with it open, ready to review. It carries over everything from the session: the spec becomes the Task's brief, along with the same repositories to work in. The session itself closes at this point. The spec stays on screen with a link through to the Task, so you can always see what was agreed. When you're happy, press **Start**. See [Creating and Running a Task](/docs/tasks/creating-and-running-a-task/). > Converting happens once. The Task doesn't stay linked to the session afterwards — it's a handover, not a live copy. --- # What is a Task? --- A **Task** is a piece of work you hand to an AI coding agent. You describe what you want; it writes the code, checks it, and opens a **pull request for each repository** it touched. You review a pull request like any other. Nothing lands without you. ## What you get back A branch and a pull request per repository, with commits describing what changed and why. Repositories the agent didn't need to touch are left alone — no empty pull requests. The diff lives in GitHub, GitLab or Bitbucket, where you already review code. Deployment.io shows you progress, logs and a link. ## It checks its own work Before finishing, the agent runs your build and tests and fixes what it can. This matters more than it sounds: **if those checks fail, nothing is committed and no pull request appears.** The Task fails instead. You review working code, or you review nothing. ## One at a time Tasks run one at a time, in the order you created them. Start three and they'll queue — the first runs, the rest wait their turn. ## Two ways to start one **Create one directly** when you already know what you want. See [Creating and Running a Task](/docs/tasks/creating-and-running-a-task/). **Work it out in a session first**, then convert it — the Task arrives in your backlog for review before it runs. See [From Spec to Task](/docs/assistant/from-spec-to-task/). You can also create Tasks from your own coding agent — see [Available MCP Tools](/docs/coding-agents/available-mcp-tools/). Still deciding? A [session](/docs/assistant/what-is-a-session/) works out what to do. A Task does it. --- # Creating and Running a Task --- ## Create one Open **Tasks** and click **Create Task**. Give it a **title**, then write the **description** — this is the brief the agent works from, so it's worth spending a minute on. Pick the **repositories** it should work in and the **branch** each should start from, and choose the **agent** and **model**. Click **Create**. It starts as soon as a slot is free. ### Writing a good description This is the single biggest lever on whether you get back something you can merge. The agent can read your code, but it can't read your mind. Say what should change, where, and what "done" looks like. Mention constraints it should respect and anything you explicitly don't want touched. A specific brief is usually the difference between one round of review and three. If you'd rather work it out interactively, start an [Assistant session](/docs/assistant/what-is-a-session/) and convert it — you'll get a far better brief than you'd write cold. ## Start one from your backlog Tasks converted from a session wait in **Backlog** until you're ready. Press **Start**, confirm the model, and it joins the queue. ## Watch it work The board groups Tasks by where they've got to; switch to **List** if you prefer a table. Click any Task to open it. Inside you'll see how far along it is, each repository with a link to its pull request once opened, and the full agent log if you want to see its reasoning. Repositories showing **No changes** are ones the agent decided didn't need touching. ## Stop, re-run, delete **Stop** halts a Task that's running or waiting. Anything already pushed by an earlier attempt stays — nothing is undone. **Re-run** gives it another go, and lets you tell the agent what to do differently first. That feedback is the useful part: _"you missed the error case in handler.go"_ gets you much further than re-running blind. New work goes onto the same branch, so an open pull request just picks it up. **Delete** removes the Task and stops any work in progress. Branches and pull requests already pushed to your repository are untouched. --- # Prerequisites and Troubleshooting --- ## What a Task needs Four things. **Create Task** checks them for you and names anything missing, with a link to fix it. | You need | Notes | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | A runner in your AWS account | Tasks run on your own infrastructure. See [Runner Installation](/docs/runner-installation/architecture/). | | It to be online | If you've nominated a default runner, that's the one that has to be up. | | An LLM key | See [LLM Providers](/docs/ai-providers/llm-providers/). | | Repositories the agent can push to | It needs permission to push branches and open pull requests. See [Adding a Repository](/docs/dashboard/adding-a-repository/). | **Which provider?** It follows the agent and the model: Codex needs your OpenAI key; Claude Code needs Anthropic — an API key or [AWS Bedrock](/docs/ai-providers/aws-bedrock/); opencode uses whichever provider serves the model you picked, so Anthropic or Bedrock for Claude models and OpenAI for GPT models. ## Common problems **"Your runner isn't active."** It hasn't checked in recently. Start it, give it a moment, then hit **Refresh**. **The Task gets all the way through and then fails.** Almost always permissions: the agent wrote the code but couldn't push it or open the pull request. Reconnect the repository with permission to write code and open pull requests — installations set up before Tasks existed often only have read access, which is why it fails at the very end rather than the start. **It failed its own checks.** Your build or tests didn't pass, so the agent committed nothing. That's deliberate. Read the log to see what broke, then re-run with feedback pointing at it. **The agent couldn't reach something.** Agents run with restricted network access. If it was blocked, you'll see which host in both the run details and the pull request. Add it under **Organization Settings → Agents → Allowed Hosts** and re-run. Hostnames must be exact — no wildcards or IP addresses. Usually this is a private package registry or an internal API. **It's sitting there not starting.** Normal if another Task is running — they go one at a time, oldest first. If nothing else is running, check your runner is online. **Nothing happened and there's no pull request.** Check whether the repositories show **No changes** — the agent may have concluded nothing needed doing. Its summary will say why. ## Who can do what Tasks follow your [roles and permissions](/docs/role-based-access-controls/introduction/). Creating, viewing, starting and deleting are separate, so a teammate might be able to see Tasks without being able to start one. --- # MCP Configuration for AI Coding Agents --- The Model Context Protocol (MCP) allows AI coding agents to interact with your deployment.io infrastructure. Once configured, agents like Claude Code, Cursor, OpenAI Codex, Gemini CLI, and Antigravity can deploy your apps, manage environments, fetch runtime logs, and monitor builds — directly from your development workflow. ## Prerequisites - A deployment.io account ## Connection Methods There are two ways to connect your coding agent to deployment.io: 1. **OAuth (recommended)** — The agent opens a browser window, you log in and approve access. No manual key copying needed. 2. **API Key** — Generate a key from the dashboard and paste it into your agent's configuration. --- ## Method 1: OAuth (Recommended) OAuth lets you connect with a single click — no API key to copy or manage. ### Claude Code CLI Run the following command: ```bash claude mcp add --transport http Deployment-io https://api.deployment.io/v1/mcp ``` Claude Code will open a browser window where you log in to deployment.io and approve access. The connection is established automatically. ### Claude Desktop 1. Go to **Customize > Connectors > + > Add custom connector**. 2. Enter the name `Deployment-io` and the URL: `https://api.deployment.io/v1/mcp` 3. Claude Desktop will open a browser for you to log in and approve access. ### Cursor 1. Open Cursor and go to **Settings > Tools & MCP**. 2. Click **Add Custom MCP**. 3. Enter the URL: `https://api.deployment.io/v1/mcp` 4. Cursor will open a browser for you to log in and approve access. ### OpenAI Codex 1. Add the server to your `~/.codex/config.toml`: ```toml [mcp_servers.Deployment-io] url = "https://api.deployment.io/v1/mcp" ``` 2. Run the OAuth login command: ```bash codex mcp login Deployment-io ``` Codex will open a browser window where you log in to deployment.io and approve access. ### Antigravity 1. Open the **Menu** in the Agent pane and go to **MCP Servers > Manage MCP Servers**. 2. Click **View raw config** to open `mcp_config.json`. 3. Add the following configuration: ```json { "mcpServers": { "Deployment-io": { "serverUrl": "https://api.deployment.io/v1/mcp" } } } ``` 4. Click **Refresh**. Antigravity will open a browser for you to log in and approve access. --- ## Method 2: API Key If your agent doesn't support OAuth, or you prefer manual configuration, use an API key. ### Step 1: Generate an API Key 1. Go to **Organization Settings > Agent Keys** in your deployment.io dashboard. 2. Click **Create New Key** and give it a descriptive name (e.g., "Claude Code Key"). 3. Copy the API key immediately — you won't be able to see it again. ### Step 2: Copy the MCP Configuration After generating your key, you'll see an MCP JSON configuration block like this: ```json { "mcpServers": { "Deployment-io": { "url": "https://api.deployment.io/v1/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` Replace `YOUR_API_KEY` with the key you copied in Step 1. ### Agent Setup with API Key #### Claude Code CLI ```bash claude mcp add --transport http Deployment-io https://api.deployment.io/v1/mcp \ --header "Authorization: Bearer YOUR_API_KEY" ``` #### Claude Desktop Add the configuration to your `claude_desktop_config.json` file: - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` Merge the MCP JSON config from Step 2 into the file. #### Cursor 1. Open Cursor and go to **Settings > Tools & MCP**. 2. Click **Add Custom MCP**. 3. Paste the MCP JSON configuration from Step 2 into the editor. 4. Save and restart Cursor. #### Windsurf 1. Open Windsurf and go to **Settings > MCP**. 2. Click **Add Server** and select **HTTP**. 3. Paste the MCP JSON configuration from Step 2. 4. Save and restart Windsurf. #### OpenAI Codex Add the server to your `~/.codex/config.toml`: ```toml [mcp_servers.Deployment-io] url = "https://api.deployment.io/v1/mcp" bearer_token_env_var = "DEPLOYMENT_IO_API_KEY" ``` Then set the environment variable: ```bash export DEPLOYMENT_IO_API_KEY=YOUR_API_KEY ``` #### Gemini CLI Run the following command: ```bash gemini mcp add -s user --transport http \ --header "Authorization: Bearer YOUR_API_KEY" \ Deployment-io https://api.deployment.io/v1/mcp ``` Or manually add to your `~/.gemini/settings.json`: ```json { "mcpServers": { "Deployment-io": { "httpUrl": "https://api.deployment.io/v1/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` #### Antigravity 1. Open the **Menu** in the Agent pane and go to **MCP Servers > Manage MCP Servers**. 2. Click **View raw config** to open `mcp_config.json`. 3. Add the following configuration: ```json { "mcpServers": { "Deployment-io": { "serverUrl": "https://api.deployment.io/v1/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` 4. Click **Refresh** and restart Antigravity. --- ## Troubleshooting - **Verify your connection works:** Run a simple prompt like "list my environments" in your agent. If the connection is working, you'll see your environments listed. - **Check the MCP URL:** Ensure the URL is exactly `https://api.deployment.io/v1/mcp` with no trailing slash. - **OAuth issues:** If the browser authorization window doesn't open, check that your agent supports OAuth-based MCP connections. Fall back to the API key method if needed. - **Regenerate the key:** If your API key stops working, it may have been revoked. Create a new one from the Agent Keys settings page. - **Revoke access:** You can revoke OAuth-connected agents or API keys anytime from **Organization Settings > Agent Keys**. --- # Available MCP Tools --- Reference of all tools exposed by the deployment.io MCP server. These are the actions a coding agent can perform when connected to your organization. ## Deployments | Tool | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `deploy_static_site` | Deploy a static site to an environment. Creates a new deployment if one doesn't exist for the repo+branch+environment combination, or triggers a redeploy if it does. Supports React, Vue, Astro, Next.js static export, Vite, and more. | | `deploy_web_service` | Deploy a web service to an environment. Creates a new deployment if one doesn't exist for the repo+branch+environment combination, or triggers a redeploy if it does. Supports any backend framework — the service must have a Dockerfile. | The agent automatically detects your project's parameters from the local codebase. For static sites, it reads your build command and output directory. For web services, it reads your Dockerfile, port, and health check path. Just tell the agent what to deploy and where. ## Environment Management | Tool | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `list_environments` | List all environments in the organization. Returns IDs, names, types, regions, classifications, and dashboard links. | | `create_environment` | Create a new environment. Supports choosing infrastructure (shared cloud or custom runners) and classification (Production/Staging/Development). | | `edit_environment` | Rename an existing environment. | ## Infrastructure | Tool | Description | | -------------- | ------------------------------------------------------------------------------------------------------------ | | `list_runners` | List available infrastructure for deploying environments. Shows shared cloud runners and custom AWS runners. | ## Monitoring & Logs | Tool | Description | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `get_deployment_logs` | Fetch runtime logs from a deployed web service. Supports time range filtering, regex search patterns, and returns up to 500 log lines per request. Use this to debug errors, monitor behavior, or audit activity. | ## Jobs & Approvals | Tool | Description | | --------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `get_job_status` | Check the status of an async job (environment creation, deployment, etc.). Returns progress, logs, and completion info. | | `get_approval_status` | Check the status of a pending approval request. Used when a deployment requires human sign-off before proceeding. | ## Usage Examples ### Example 1: Deploy a static site to staging Ask your coding agent: > "Deploy my app to staging" The agent will: 1. Detect your repository, branch, build command, and output directory from the local project 2. Call `list_environments` to find the staging environment 3. Call `deploy_static_site` with the detected parameters 4. Poll `get_job_status` until the build completes 5. Report back with the live URL ### Example 2: Deploy a web service Ask your coding agent: > "Deploy my API server to staging" The agent will: 1. Detect your repository and branch from the local project 2. Read the Dockerfile for the EXPOSE port, or search app code for listen calls 3. Search for a health check endpoint (e.g., `/health`, `/healthz`) 4. Call `list_environments` to find the staging environment 5. Call `deploy_web_service` with the detected parameters 6. Poll `get_job_status` until the build completes 7. Report back with the service URL If no Dockerfile exists, the agent will create one for your framework, commit it, push, and then deploy. ### Example 3: Deploy to production (with approval) Ask your coding agent: > "Deploy to production" The agent will call `deploy_static_site` or `deploy_web_service` targeting the production environment. If approval is required, the agent will: 1. Return a link to the approvals page in the dashboard 2. Wait for a team member to review the agent's summary of what is being deployed and why 3. Once approved, the build starts automatically 4. The agent polls `get_approval_status` and `get_job_status` to report the result ### Example 4: Deploy a specific branch Ask your coding agent: > "Deploy the feature-xyz branch to staging" The agent will use `git show feature-xyz:package.json` to read the correct build configuration from that branch, then deploy it to the staging environment. ### Example 5: Create an environment on custom infrastructure Ask your coding agent: > "Create a new staging environment called 'api-staging' on my AWS account" The agent will: 1. Call `list_runners` to find available infrastructure 2. Show you the options (shared cloud vs. your custom AWS runners) 3. Call `create_environment` with the selected runner, name, and classification 4. Return a link to the new environment in the dashboard ### Example 6: Check job and approval status Ask your coding agent: > "What's the status of my latest deployment?" The agent will call `get_job_status` with the job ID to check progress, show build logs, and report whether the deployment succeeded or failed. If the deployment requires approval, the agent can call `get_approval_status` to check whether a reviewer has approved it. ### Example 7: Fetch error logs from a service Ask your coding agent: > "Get the last hour of error logs from my production API" The agent will: 1. Call `list_environments` to find the production environment 2. Call `list_deployments` to find the API service 3. Call `get_deployment_logs` with a time range of the last 60 minutes and a search pattern like `error|exception` 4. Summarize the errors found and suggest fixes ### Example 8: Automate error monitoring with scheduled tasks Combine `get_deployment_logs` with Claude Code's `/schedule` command to create an autonomous error monitoring pipeline. Run `/schedule` in Claude Code and configure a task with this prompt: > "Fetch error logs from my production service for the last hour. Analyze the errors, trace root causes in the codebase, and open a PR if you find fixable bugs." The scheduled task runs in the cloud on Anthropic's infrastructure — it works even when your machine is off. Claude clones your repo on each run, fetches logs, analyzes errors, and opens pull requests with fixes. Read the full guide: [Autonomous Error Fixing with Scheduled Tasks](/blog/autonomous-error-fixing-with-scheduled-tasks/). ## Access Control - **Scopes**: Each tool requires specific scopes on the API key (e.g., `environments:read`, `deployments:*`). Scopes are configured when the key is created or during OAuth authorization. - **RBAC**: Members only see and modify resources they have been granted access to. Owners have full access. - **Approvals**: Deployments to production environments require human approval before proceeding. Staging and development environments are auto-approved by default. Approval policies are configurable per agent key. ## Shared Cloud Infrastructure Note Deployments on the shared cloud runner (Deployment.io cloud) are automatically deleted after 24 hours. Use a custom runner connected to your own AWS account for persistent deployments. --- # The Deployment.io Skill --- The deployment.io skill is a [SKILL.md](https://agentskills.io/specification)-compliant bundle that teaches your coding agent how to deploy on deployment.io — git pre-flight, parameter detection, log-based diagnosis, and approval handling. It pairs with the [MCP server](/docs/coding-agents/mcp-configuration/) and works across Claude Code, Claude Desktop, Cursor, OpenAI Codex, Gemini CLI, and 25+ other SKILL.md-compliant agents. Source: github.com/deployment-io/skills (MIT, semver). ## What the Skill Adds The MCP server gives your agent the **tools** (`deploy_static_site`, `deploy_web_service`, `list_environments`, etc.). The skill gives it the **playbook**: - Framework → `publish_directory` table (Vite/Svelte/Astro → `dist`, CRA → `build`, Next.js static → `out`, Hugo → `public`, Jekyll → `_site`). - How to pick `is_spa` correctly (client-side routers vs. static site generators). - Where to find the `port` inside a container (Dockerfile `EXPOSE`, app listen calls, `PORT` env). - Health-check route detection (`/health`, `/healthz`, `/ping`, `/ready`). - Git pre-flight: `git fetch origin`, check unpushed commits, capture the exact SHA for `commit_hash`. - Diagnose a bad deploy: use `get_deployment_logs` + `get_job_status` to read failure output. - Approval flow: poll `get_approval_status`, don't retry the original call. Without the skill, your agent has the tools but has to re-derive these details on each session. With the skill, the runbook is loaded automatically when the prompt matches a deploy intent. ## Prerequisites - A deployment.io account. - The deployment.io MCP server connected in your agent — see [MCP Configuration](/docs/coding-agents/mcp-configuration/). The skill calls these tools; without the MCP server, the skill has nothing to invoke. ## Install Clone the repo once: ```bash git clone --depth 1 --branch v0.1.0 https://github.com/deployment-io/skills.git /tmp/dio-skills ``` Then copy the skill folder into the path your agent reads from: | Agent | Command | | ---------------------------- | ------------------------------------------------------------------------------------------- | | Claude Code / Claude Desktop | `mkdir -p ~/.claude/skills && cp -r /tmp/dio-skills/skills/deployment-io ~/.claude/skills/` | | Codex CLI | `mkdir -p ~/.codex/skills && cp -r /tmp/dio-skills/skills/deployment-io ~/.codex/skills/` | | Gemini CLI | `mkdir -p ~/.gemini/skills && cp -r /tmp/dio-skills/skills/deployment-io ~/.gemini/skills/` | | Cursor | `mkdir -p ~/.cursor/skills && cp -r /tmp/dio-skills/skills/deployment-io ~/.cursor/skills/` | > **Important:** Restart your agent after copying. Skills are scanned at session start, not at runtime — if you skip this step, the skill won't load. ## Verify It's Loaded Start a new conversation and ask: > "What skills do you currently have loaded?" Your agent should list `deployment-io`. For a deeper check, ask about specific content the skill owns: > "I'm planning to deploy a Vite app on deployment.io — what publish_directory should I use, and what about a Hugo site?" A skill-loaded agent answers with the framework table verbatim. A generic agent will either guess or say it doesn't know. ## Troubleshooting **Skill doesn't appear when I ask "what skills are loaded?"** Confirm the path: `ls ~/.claude/skills/deployment-io/SKILL.md` (adjust path per agent). The file must be directly inside a `deployment-io/` folder in your agent's skills directory, not nested deeper. Restart your agent — skills are only scanned at session start. **Skill is listed but doesn't activate on deploy prompts.** Try a more explicit phrase: _"Use the deployment-io skill to deploy my app to staging."_ If it activates now, the issue is trigger-phrase matching — try rephrasing your natural request. If it still doesn't activate, check the frontmatter parses: `yq e --front-matter=extract ~/.claude/skills/deployment-io/SKILL.md` — you should see `name` and `description` fields. **Skill activates but tool calls fail.** The MCP server isn't connected. The skill calls tools like `deploy_static_site` and `list_environments` that come from the deployment.io MCP server. Ask your agent: _"Is the deployment-io MCP server connected?"_ If not, follow the [MCP configuration guide](/docs/coding-agents/mcp-configuration/). **Agent ignores the framework table or keeps asking for parameters it should know.** Your agent may have an older skill version cached. Delete `~/.claude/skills/deployment-io` (or your agent's path), re-run the install, and restart. ## Update Re-clone with a new tag and re-copy to the agent's skills path: ```bash git clone --depth 1 --branch https://github.com/deployment-io/skills.git /tmp/dio-skills cp -r /tmp/dio-skills/skills/deployment-io ~/.claude/skills/ # or your agent's path ``` Restart the agent to pick up the new version. ## License MIT. Fork it, extend it, customize it for your team. --- # Architecture --- Deployment's architecture is designed to be scalable, fault-tolerant, distributed, and multi-tenant. Our control plane runs on AWS; the data plane runs in your cloud account. The architecture has two halves: ## Control Plane The control plane consists of the microservices, dashboards, and databases that run on deployment.io's AWS. Its responsibilities: 1. user management 2. creating, allocating, and scheduling jobs that the data plane executes 3. billing 4. the public API ## Data Plane The data plane is the runner — a client that runs in your cloud account and executes the workloads the control plane sends it. Its responsibilities: 1. **Deployment jobs:** checking out source code, building it, deploying it, creating previews, deleting cloud resources when deployments are removed. 2. **Task agent runs:** running AI coding agents in isolated containers that read from and write to your repositories, then open pull requests for review. The runner needs only a private subnet and an outbound HTTPS connection to deployment.io. All traffic between control plane and data plane is encrypted over TLS. Your source code and cloud credentials never leave your cloud account — only job state, logs, and metadata flow back to deployment.io.
Architecture Diagram

deployment_architecture For the install steps, the resources the CloudFormation stack creates in your AWS account, cost details, and uninstall instructions, see [AWS Setup](/docs/runner-installation/aws-setup/). --- # Local Setup is no longer supported --- The local runner installation has been retired. Deployment.io supports a single runner installation path going forward — the AWS-based runner. If you previously ran the runner locally for individual development, switch to the AWS runner: it takes about 5 minutes to install via CloudFormation, scales to zero when idle, and runs deployments and Tasks in your own AWS account so your code and credentials never leave it. → [AWS Setup](/docs/runner-installation/aws-setup/) → [Architecture](/docs/runner-installation/architecture/) If you have a local runner already running, it will continue to operate but won't receive updates. Email us at hello@deployment.io if you have questions about migrating. --- # AWS Setup --- Install the runner on your AWS account by launching our CloudFormation stack — it takes about 5 minutes. For the high-level picture of how the runner fits into deployment.io's architecture, see [Architecture](/docs/runner-installation/architecture/). ## What gets installed in your AWS account The CloudFormation stack creates the resources below. All resources are tagged `created by: deployment.io` so you can audit and clean up after. ### Compute - **ECS cluster** (`ecs-{orgID}`) with a Fargate capacity provider plus an EC2 capacity provider. - **AWS controller** — a small ECS task on **Fargate** (0.25 vCPU, 0.5 GB) that runs continuously. Polls deployment.io for jobs and dispatches them. - **Runner** — an ECS task on **EC2 m6a.large** (6 GB) that scales from zero. Only runs when there's a deployment or Task to execute. Mounts the host's Docker socket so it can build images. - **Auto Scaling Group** backing the EC2 capacity (`min: 0`, `max: 2`). - **EC2 Launch Template** that defines the EC2 instance for the ASG. ### IAM (four roles) - **Lambda role** — used only during stack creation by the bootstrap Lambda. Can create the ECS service-linked role and the task-execution role. - **ECS Instance role** — attached managed policy `AmazonEC2ContainerServiceforEC2Role`, lets the EC2 host register with ECS. - **Task Execution role** (`eTERole-…`) — created by the bootstrap Lambda. Has `AmazonECSTaskExecutionRolePolicy`, `CloudWatchFullAccess`, and `SecretsManagerReadWrite`. - **Task Role** (`dr-task-role-…`) — runtime role assumed by the runner container. Has `iam:PutRolePolicy / GetRolePolicy / GetRole / PassRole` on `role/*`, and `iam:CreateServiceLinkedRole` for ECS, ELB, and RDS service-linked roles. The runner uses this role to provision the AWS resources your deployments need. ### Networking - The runner EC2 instance lives in the **subnet you select** during installation. No public IP. Outbound only. - The Fargate AWS controller runs in the same subnet with `AssignPublicIp: ENABLED` so it can reach `go.deployment.io:443` (the only outbound endpoint the runner talks to). ### Other - **Bootstrap Lambda** (Python 3.9, 100s timeout) — runs once on stack create to set up the ECS service-linked role. Does nothing after. - **CloudWatch log groups:** `dr-logs-group-…` (runner output) and `dr-aws-controller-logs-group-…` (controller output). Auto-created on first job. ## Install steps
1. Open the runner setup
In the dashboard, go to Org Settings → Runners and click the Add runner button. (The same install flow is also available inline from the environment creation page if you're already there.) 2. Launch CloudFormation stack
Select the region where you want to install the runner and launch the CloudFormation stack.
launch-deployment-runner-cloudformation-template
3. Select the subnet where you want to install the runner
Sign in to your AWS account. On the CloudFormation stack creation page, select the subnet on which you want to install the runner. Then click Create stack to start the installation. deployment-runner-subnet
4. Check the installation logs
Watch the CloudFormation event logs to confirm the runner installed without errors. We don't have visibility into AWS-side errors during installation, so the AWS console is the source of truth here.
deployment-runner-installation-event-logs ## Cost on your AWS bill - **Idle baseline (~$8/mo):** the always-on Fargate AWS controller (0.25 vCPU + 0.5 GB) plus negligible CloudWatch logs. - **Active runtime:** the EC2 m6a.large adds ~$0.09/hr while a job is running, then scales back to zero. So 1 active hr/day adds ~$3/mo; 8 active hrs/day adds ~$20/mo. - **Tasks impact:** Task agent runs are typically longer than deployment jobs (multi-step agent sessions, often 10–30 min). A team running ~20 Tasks/day on top of regular deployments will see EC2 hours accumulate faster. In practice, most teams land between **$10 and $40/month**. Heavier Task workloads can push higher — monitor the ECS cluster's compute time in CloudWatch if you want a precise number. ## Uninstalling Delete the CloudFormation stack from the AWS console (or `aws cloudformation delete-stack`). Every resource the stack created is removed automatically — IAM roles, ECS resources, Auto Scaling Group, Launch Template, Lambda, log groups. Nothing else needs cleanup.
Email us at hello@deployment.io if there's any installation error or you have other questions. --- # Static Website on AWS --- For a static website, using a backend server like NodeJs is a waste of valuable compute resources. Speed and performance are critical for good SEO and user experience. To save on compute resources and cost, Deployment uses a combination of S3 bucket and Cloudfront to deploy a static website to your AWS cloud. The deployed static website is highly performant, scalable, and cost-effective. --- # Web Service on AWS --- Deployment uses AWS ECS and Fargate to deploy your web services. ECS and Fargate are very cost-effective since you pay only for usage. A private VPC, Subnets, and NAT are created per runner. So you can easily isolate your testing and production environments according to AWS best practices. Deployment uses an Application Load Balancer to make sure your web services can be easily scaled horizontally. Additionally, AWS ECR is used as a registry to save your built docker images. --- # Adding a Repository --- 1. Add repositories by connecting your GitHub or GitLab accounts through oauth with Deployment. adding a repository
2. Give access for selected or all repositories.
select repositories --- # Creating an Environment --- Create an environment with one click using Deployment.
1. Add name, runner, and region for the environment.
new environment details
2. Add environment variables and secret files. {" "}

Deployment encrypts all environment variables and secret files using industry standard AES 256 encryption.

secret files --- # Deploying a Static Website --- A static site is rendered on the client side in the browser and doesn't require any server side rendering. Hence, there is no need for server side compute resources. Some popular frameworks for building a static site are: - ReactJs - VueJs - GatsbyJs - NextJs - Astro - Hugo Deployment makes it super easy to deploy a static site on your AWS cloud. ### Steps 1. Click on the Static site button in the dropdown to create a deployment. {" "}

create static site
2. Select a repository you want to deploy. {" "}

select static site repository
3. Input details for the static site deployment and deploy a static site
static site details
--- # Deploying a Web Service --- A backend web service requires server side compute resources to execute business and other logic on the backend. Some popular technologies for building backend services are: - Python - Golang - Java - Rust - NodeJS - Ruby on Rails Easily deploy a backend API or a Web service with one click. ### Steps 1. Click on the Web service button in the dropdown to create a deployment.
create web service
2. Select a repository you want to deploy.
select web service repository
3. Input details for the web service deployment and deploy the web service
web service details
--- # Adding Custom Domains --- Adding a custom domain is super easy on Deployment. ### Steps 1. Add a custom domain for your deployment by clicking on the Domains tab.
custom domain Deployment takes care of redirects from www to your root domain and vice versa.
2. Create certificate and verify your domain for https
Deployment automatically creates a certificate for you using AWS certificate manager.
custom domain 3. Verify and update DNS settings accordingly at your domain provider. --- # Adding Response Headers --- Having the ability to set response headers is very critical for static sites. Especially for proper cache behavior in the browser. Deployment makes it very easy to add response headers for your static sites.
On the deployment page, add the response headers under the Headers tab
add response headers --- # Checking Build Logs --- Deployment generates real-time build logs for all builds. You can easily check for any build errors by clicking the icon on the builds page. The build logs also have a detailed info on the AWS infrastructure that gets created/updated during the build.
build logs > **Tip:** You can also fetch logs programmatically using the `get_deployment_logs` MCP tool. This lets AI coding agents access your logs directly from your development workflow. See [Available MCP Tools](/docs/coding-agents/available-mcp-tools/) for details. --- # Checking Application Logs --- Deployment pushes all application logs for a web service to AWS Cloudwatch automatically. You can check all application logs on Cloudwatch. application logs > **Tip:** You can also fetch application logs programmatically using the `get_deployment_logs` MCP tool. This lets AI coding agents analyze your runtime errors directly from your development workflow — or even [automate error monitoring on a schedule](/blog/autonomous-error-fixing-with-scheduled-tasks/). See [Available MCP Tools](/docs/coding-agents/available-mcp-tools/) for details. --- # Deleting a deployment --- You can easily delete a deployment when it's no longer needed.
This deletes all the underlying AWS cloud infrastructure for that deployment. So you're no longer billed for that.
On the deployment page, you can delete the deployment under the Settings tab.
deleting a deployment --- # Automatic Deployment on Git Push --- Deployment enables you to auto deploy code on every Git push for continuous integration and delivery.
On the deployment page, enable auto deploy under the Auto deploy tab.
auto deploy --- # Creating Preview Deployments --- Deployment can automatically create a preview build when a pull request is created against a branch. This can help you during code reviews since you can be confident of the changes before they're deployed to production. On the deployment page, enable previews under the Previews tab.
previews
By default, all previews are created in the same environment as the base branch deployment. Once a preview is created, you can update the environment by editing the preview and redeploying. edit preview Messages and comments are added accordingly for the pull request on GitHub and GitLab. The preview and all the cloud sources created for the preview are deleted automatically, 30 minutes after the PR is merged or closed. --- # Getting Alerts on Slack --- You can easily connect your Slack workspace to get alerts for any updates to your deployment. ### Steps 1. Connect your Slack workspace.
On the deployment page, add our Slack app to your workspace under the Notifications tab.
connect slack workspace
2. Select Channel.
Once your Slack workspace is connected, you can select the channel on which you want to receive the updates for that deployment.
You can setup different channels for different deployments. For example, the critical production deployments can use a different channel from test deployments.
select slack channel --- # Introduction --- Deployment supports advanced and fine-grained Role Based Access Control (RBAC) to make sure our clients are secure and compliant.
For example, you may want to make sure that only certain users have access to the production environment and deployment. This can be easily achieved using our RBAC functionality. ```english RBAC feature is available in the Hacker Pro and the Team plans ``` --- # Creating Roles ---
In Org Settings, navigate to Roles settings.
Then click on Role + to create a role. Enter name and description and create a role.
create roles ```english Only organization owners can create a role ``` --- # Inviting Users ---
In Org Settings, navigate to Users settings.
Then click on Invite User to invite a user. Enter user's email and select a role.
inviting users ```english Only organization owners can invite users ``` --- # Sharing Deployments --- ### Steps **1. Share deployment** To share a deployment with other users or a role, click on Share button on the deployment page. sharing a deployment **2. Select shared deployment action** Select what action a user or a role can take with the shared deployment. select deployment access Only organization owners or deployment admins can share a deployment. --- # Sharing Environments --- ### Steps **1. Share environment** To share an environment with other users or a role, click on Share button on the environment page. sharing an environment **2. Select shared environment action** Select what action a user or a role can take with the shared environment. select environment access Only organization owners or environment admins can share an environment. --- # Getting free AWS credits --- AWS gives you an incentive to use their services by giving you free credits. There are various programs through which you can get free AWS credits. ### $5,000 credits for 2 years Get $5,000 in free credits by signing up for the free Y Combinator Startup School course. ### $1,000 credits for Bootstrapped startups Get $1,000 in free credits by applying to AWS Activate. ### $100,000 credits for VC funded startups Get $100,000 in free credits by applying to AWS Activate. --- # Deploy a Go Gin Web Server on AWS --- You can use this as a starting point for deploying a Go Gin server on AWS using Deployment.io. ## Deployment 1. Fork deployment-io/golang-gin-gonic-starter on GitHub. 2. Create new Web Service on Deployment.io. 3. Connect and add the forked repository. 4. Select Go as the runtime. 5. Input port number as 8080 since our server runs on that port. Change it according to your code. 6. Input health check path as /ping . Change it according to your code. 7. We autodetect the Build and Start commands using NixPacks so you can ignore them.
Your Go Gin web server will be available on your AWS ALB URL in the dashboard as soon as the build finishes. --- # Deploy a NodeJs Express Web Server on AWS --- You can use this as a starting point for deploying a NodeJs Express server on AWS using Deployment.io. ## Deployment 1. Fork deployment-io/express-hello-world on GitHub. 2. Create new Web Service on Deployment.io. 3. Connect and add the forked repository. 4. Select Node as the runtime. 5. Input port number as 3001 since our server runs on that port. Change it according to your code. 6. Input health check path as / . Change it according to your code. 7. We autodetect the Build and Start commands using NixPacks so you can ignore them.
Your NodeJs Express web server will be available on your AWS ALB URL in the dashboard as soon as the build finishes. --- # Deploy Python Flask Web Server on AWS --- You can use this as a starting point for deploying a Python Flask server on AWS using Deployment.io. ## Deployment 1. Fork deployment-io/flask-hello-world on GitHub. 2. Create new Web Service on Deployment.io. 3. Connect and add the forked repository. 4. Select Python as the runtime. 5. Input port number as 8000 since our server runs on that port. Change it according to your code. 6. Input health check path as / . Change it according to your code. 7. We autodetect the Build command using NixPacks. Use the following value for Start command: gunicorn app:app . Change it according to your code.
Your Python Flask web server will be available on your AWS ALB URL in the dashboard as soon as the build finishes. --- # Deploy Rust Rocket Web Server on AWS --- You can use this as a starting point for deploying a Rust Rocket server on AWS using Deployment.io. ## Deployment 1. Fork deployment-io/rocket-rust-hello-world on GitHub. 2. Create new Web Service on Deployment.io. 3. Connect and add the forked repository. 4. Select Rust as the runtime. 5. Input port number as 8000 since our server runs on that port. Change it according to your code. 6. Input health check path as / . Change it according to your code. 7. We autodetect the Build and Start commands using NixPacks so you can ignore them.
Your Rust Rocket web server will be available on your AWS ALB URL in the dashboard as soon as the build finishes.