> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy your first agent

> Start from one of four templates or from your own repository, set its level and budget, and deploy.

> [!NOTE]
>
> **Not yet released.** This guide describes implemented changes awaiting rollout. Availability requires the corresponding backend and dashboard release.

## Goal

Get a working agent running on StackShift from a template, then change it into your own.

## Prerequisites

* A StackShift account and, to use the CLI, `stackshift login`.
* A GitHub account connected to StackShift, so the template can be copied into your repositories.
* For your own repository: a `Dockerfile` in the folder you deploy, and a `stackshift.yaml` in it, or let the form write the agent block for you.

## Workflow

**Step 1**

Open Agents, choose New agent, and pick a template and a language. Or run `stackshift agents create --name "Inbox helper" --template inbox-helper --language typescript`.

**Step 2**

Leave the level on “Ask me every time” for a first agent. Check the budgets, what wakes the agent and the internet access, then deploy.

**Step 3**

Watch the deploy steps: copy, build, address, start and first wake. When they finish, the agent has its address.

**Step 4**

Trigger it the way the template expects: email its address, wait for its schedule, or send it a webhook. Open the run on its page to see each model call, action and cost.

**Step 5**

Change the code in the copy StackShift made in your GitHub, push, and press Deploy or run `stackshift agents deploy <agent>`. Roll back with `stackshift agents rollback <agent> <version>`.

## The four templates

Each template comes in TypeScript and Python. Each is a small repository with a `stackshift.yaml`, a `Dockerfile`, the code, and a README in plain words. StackShift keeps the templates in public repositories and copies the one you pick into your GitHub.

The templates leave your own content empty on purpose: instructions, prices and addresses are for you to write. They do not ship with sample text that could go out by mistake.

* Inbox helper: reads its inbox, answers from instructions you write, and hands everything else to you. With no instructions it hands over every email and uses no AI credits.
* Quote agent: answers requests for quotes with agreements, from a price list you write, inside the limits you set for its inbox. It uses no AI credits.
* Scheduled report: wakes on a schedule, fetches data from an address you allow, writes a short summary and emails it to you.
* Blank agent: one event handler and one example action.

## The Dockerfile

StackShift builds your agent from the `Dockerfile` in its folder. Install your packages, copy the code into `/app` and build it there. The start command in `stackshift.yaml` runs from `/app`. `/workspace` is the agent’s own folder, which keeps its files between sleeps. The templates show how, for TypeScript and Python. A build command in `stackshift.yaml` is not used.

Pin each base image to its digest, for example `FROM node:22-bookworm-slim@sha256:…`, so every build uses exactly the same image. The image needs `/bin/sh`, which the usual Node and Python images have.

StackShift adds its own small runner on top of your image when it builds. Your start command then runs as a user called `sandbox`, not as root, so your code in `/app` only needs to be readable, and anything your agent writes goes in `/workspace` or `/tmp`.

## Start from your own repository

Pick the repository, branch and folder. StackShift reads `stackshift.yaml` from that folder. If it has no agent in it, the form shows a default agent block, which you can change before you deploy. The file can also hold your apps and databases; an agent can connect to them the usual way.

If the folder holds more than one agent, put each in its own folder and pick the folder when you deploy.

## Start from the terminal

`stackshift agents init` adds an agent block to `stackshift.yaml` and writes a Dockerfile and a starter handler with one example action. It never overwrites a file unless you pass `--force`.

The CLI also has `list`, `deploy`, `rollback`, `stop`, `start`, `delete`, `runs`, `spend`, `secrets set` and `unset`, and `budget set`. `secrets set` reads the value from standard input, so it never lands in your shell history.

```bash theme={null}
stackshift agents init --name "Supplies agent" --language typescript
npm install @stackshift-cloud/agent
git add . && git commit -m "Add an agent" && git push
stackshift agents create --name "Supplies agent" --repository github.com/millsco/supplies-agent --branch main
stackshift agents show supplies-agent
stackshift agents logs supplies-agent --follow
```

## Expected result

> [!TIP]
>
> The agent is deployed, asleep, with its own address. It wakes on its first event, does its job inside its level and budget, and records the run.

## Common failures

> [!WARNING]
>
> * The deploy stops with “This agent needs a Dockerfile in its folder”. Add a `Dockerfile` next to `stackshift.yaml`. The templates include one.
> * The deploy fails at build. The failed step shows the build output. Fix it in your repository and deploy again.
> * The build stops with “must be scratch, a prior stage, or a digest-qualified image”. A `FROM` line names an image by tag only. Add its digest, as the templates do.
> * The first run fails with “Set REPORT\_SOURCE\_URL for this agent first”. The Scheduled report needs its keys before it can run. Save them with `stackshift agents secrets set` and deploy again.
> * An action shows as waiting. At “Ask me every time”, anything that changes something waits for you. Approve it on the card, or raise the level.

## Related guides

> [card] [The agent block in stackshift.yaml](https://docs.stackshift.cloud/ai-features/hosted-agents-manifest.md)
>
> Reference for the `type: agent` service: what wakes the agent, how it pays, what it may reach and which actions it has.

> [card] [Internet access and secrets for agents](https://docs.stackshift.cloud/ai-features/hosted-agents-internet.md)
>
> An agent reaches only StackShift and model access until you allow more. Its keys for other services stay secret, and some it never holds at all.

> [card] [The agents SDK for TypeScript and Python](https://docs.stackshift.cloud/ai-features/hosted-agents-sdk.md)
>
> The packages `@stackshift-cloud/agent` and `stackshift-agent` give your code events, governed actions, StackShift calls, state, model clients and adapters for the Claude Agent SDK and the OpenAI Agents SDK.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.