Skip to main content
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

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.
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.
3
Watch the deploy steps: copy, build, address, start and first wake. When they finish, the agent has its address.
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.
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.

​
Expected result

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

  • 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.

The agent block in stackshift.yaml

Reference for the type: agent service: what wakes the agent, how it pays, what it may reach and which actions it has.

Internet access and secrets for agents

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.

The agents SDK for TypeScript and Python

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.