Skip to main content
Not yet released. This guide describes implemented changes awaiting rollout. Availability requires the corresponding backend and dashboard release.

​
Goal

Understand what an agent on StackShift is, what you get when you deploy one, and what StackShift does and does not enforce.

​
Prerequisites

  • A StackShift account with room for another agent on your plan.
  • Agent code in TypeScript or Python, from a template or from your own repository, with a Dockerfile that builds it. Other languages run too, but the SDK is TypeScript and Python first.

​
Workflow

1
Open Agents in the product switcher and choose New agent, or run stackshift agents create.
2
Pick a template or your own repository. StackShift builds the agent from its Dockerfile and reads the agent block in stackshift.yaml, or writes one for you.
3
Choose its level, how it pays for models, its budgets, what wakes it and what it may reach. Deploy.
4
Watch it sleep, wake on an event, and show each run, action, approval and cost on its page. Press Stop to halt everything at once.

​
What you get when you deploy

  • A place to run that sleeps when idle and wakes when an email, an agreement, a message from another agent, a schedule, a webhook or your approval arrives.
  • Model access without your model keys. The agent calls Anthropic or OpenAI through StackShift. Usage comes out of AI credits, or out of your own provider key, which the agent never sees.
  • An address: an agent inbox, and agreements if you switch them on.
  • Rules for its own actions. You list the agent’s own tools, such as “refund an order”, each with a risk. Approval cards, levels, untrusted-text flags, the stop button and the action log then govern those tools the same way they govern Stackie and connected agents on StackShift’s own actions.
  • One page with its runs, actions, approvals waiting and spend, and a Stop button.

​
How a request flows

Something arrives, such as an email to the agent’s inbox. StackShift turns it into an event and delivers it to your agent’s handler, waking the agent if it is asleep. Delivery is at least once, so the agent sees an event again if a run fails. Your code runs. It calls models through StackShift, calls StackShift actions through the agent’s own connection, and asks StackShift before any of its own actions above the risk “read”. StackShift applies the agent’s level, any limits, untrusted-text tracking and the stop button to each of those. An action that needs your approval is saved and the run ends. When you decide, a new event wakes the agent and the action runs with exactly the arguments you approved. After the idle time you set, the agent sleeps.

​
What it costs

There is no fee per agent. An agent costs what it uses: running time while it is awake and storage while it sleeps, AI credits for model calls (nothing extra when it uses your own provider key), and the mail and Durable Jobs allowances it already draws on. Running time is charged each hour, a few minutes after the hour ends. Each month your plan includes some running time for sandboxes and agents: ₦1,000 on Hosted Free, ₦3,000 on Ignite, ₦5,000 on Pro and ₦30,000 on Enterprise. After that it comes from your wallet, in Naira or US dollars. If your wallet can’t cover an hour, your agents pause and your sandboxes sleep, and you get an email. Top up and the agents start again by themselves. Plans set how many agents you can have: 1 on Hosted Free (it must sleep), 3 on Ignite, 10 on Pro, custom on Enterprise. A new account gets 1 agent, no internet beyond StackShift and model access, and AI only from credits, until it has been open for a week or has paid.

​
The honest limit

You own the agent’s code, so you can skip the wrapper that asks StackShift before an action. That wrapper governs your agent’s model, which is what goes wrong in practice. It is not a guard against the developer. What StackShift enforces whatever the code does: model calls, which go through StackShift; actions on StackShift, which go through the agent’s connection; email and agreements; and internet access, which is limited to the addresses you allow.

​
Expected result

Your agent runs on StackShift, wakes only when something arrives, and every model call, action, email and internet request it makes is governed and recorded.

​
Common failures

  • Your plan has no room for another agent. The Agents page shows how many you use and how many your plan allows.
  • A new version waits for you instead of running. It asks for more than the version before it, such as a new StackShift permission, an action that asks you, a larger budget or wider internet access. Review it in the agent’s settings and activate it.
  • The agent stopped on its own. The agent’s page says why: its monthly AI budget, an abuse rule, five failures in a row, or a repeated request.

Deploy your first agent

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

Your agent’s own actions: risk, approvals and levels

Declare the tools your agent has, give each a risk, and let StackShift apply the agent’s level, approvals and untrusted-text checks before they run.

Model access for agents

Your agent calls Anthropic or OpenAI through StackShift with a short-lived token. No provider key is ever in the agent.

Budgets, stopping and runaway protection

Three budgets, a Stop button that halts everything at once, and layers that stop an agent that loops or fails.