Start guide
In this tutorial you give Spotlight its first piece of work and watch an AI agent pick it up.
In Spotlight, a piece of work is a task. A task moves through a series of steps, such as triage, then writing a spec, then building it. Spotlight calls the series a line and each step a station. At most stations an AI coding agent does the work, then passes the task on to the next station or stops to ask you a question.
Spotlight keeps track of the work, and the agents run on a computer you provide. Here that is your own computer, which Spotlight calls a host.
By the end you will have:
- created a workspace
- set up your computer so agents can run on it
- given a task to the first station of a line, and answered the question its agent asks you
This tutorial uses Spotlight at app.usespotlight.ai. On a
self-hosted Spotlight, use the
deployment's address wherever this tutorial shows app.usespotlight.ai.
Before you start
You need:
- A GitHub account. Spotlight signs you in with GitHub.
- A Mac or Linux computer with Docker Desktop, OrbStack, Colima or Podman installed and running. Spotlight runs each agent inside a container, so the agent can't reach the rest of the computer.
- An Anthropic API key. The agents in this tutorial are Claude Code, and they need the key to use Claude.
Create a workspace
A workspace holds everything Spotlight knows about your organisation: its people, its teams, and each team's lines and tasks.
Open app.usespotlight.ai and click Continue with GitHub. Approve the sign-in on GitHub.
Spotlight asks you to name the workspace. Notice that the URL field fills itself in from the name. Click Continue.
Spotlight asks for a first team, a group of people who share lines and an inbox. Name it and click Create workspace.
Spotlight opens the Inbox. This is where anything that needs a person lands, such as an agent's question. It already holds one item: Set up your team. Open it. It lists three steps, Install the GitHub App, Connect a host and Set up configuration as code, and none has a check mark yet. A host is a computer that runs agents. A harness is the AI coding tool an agent runs, Claude Code in this tutorial. You come back to the second step later.
In the sidebar, under Your teams, expand your team, then Lines. The team already has two lines. Delivery takes a request from Triage through to Code Review, and Review looks over pull requests. This tutorial uses Delivery.
Let your computer take work from Spotlight
Spotlight hands work to a pool, a group of computers that all prove who they are with the same secret token. Here you create a pool with only your computer in it.
In Spotlight, open the workspace menu at the top of the sidebar, choose Settings, then Runners. This page lists the computers that run agents for the workspace. It has none yet, and reads No hosts yet. Click Add the first host.
The Add a host page has three steps. Under Create a pool, Pool name
already reads my-computer-1. Leave it and click Create pool.
The next step, Add the machine to the my-computer-1 pool, now shows a command that installs Spotlight on a computer, with the pool's token already in it. Spotlight shows the token only this once, so keep the page open.
Start running agents on your computer
Open a terminal. The agents use Claude, so they need your Anthropic key. Save it in the file Spotlight reads on your computer when it starts:
mkdir -p ~/.spotlight
echo 'ANTHROPIC_API_KEY=<your Anthropic key>' >> ~/.spotlight/sandbox.env
chmod 600 ~/.spotlight/sandbox.envThe commands print nothing.
On the Add a host page, click Copy command and run it in the terminal. It
looks like this, with the pool's token in place of <pool token>:
curl -fsSL https://app.usespotlight.ai/api/install.sh | SPOTLIGHT_TOKEN=<pool token> shThe command downloads the spotlight program and the container image agents
run in, then sets the program to keep running in the background. The image
download takes a few minutes. The last line reads:
spotlight host: serving https://app.usespotlight.ai: this machine shows on the workspace's Runners page once it reportsIf it stops with no container runtime answered, Docker, or whichever of the
tools above you use, isn't running. Start it and run the command again.
Watch the last step, Wait for the host to connect. Within a minute of the command finishing, your computer connects and Spotlight opens the Runners page. Your computer appears in its own row, with Pool my-computer-1 under Serves. Under Harnesses are the logos of the coding tools it can run, Claude Code among them. Its status reads Idle: it is connected and waiting for work.
Go back to Inbox and open Set up your team. Connect a host now has a check mark: your computer is ready to take work.
Give Triage a task
Triage is the first station of Delivery. Its agent reads a new task and decides what it needs next.
Open Delivery. The board lists the stations where agents work, one below the other: Triage, Spec, Implementation and Code Review. Each is a section with its tasks underneath. New tasks start in the backlog, where they wait until someone moves them on. Click Backlog at the top of the board to see only the backlog.
Click + beside Backlog. In Task title, enter:
Write a welcome note for new teammatesIn Add description…, enter:
Write a short welcome note for the people joining our team next week.
Only I know who they are and what they'll work on.Click Create task.
The task needs no code. It leaves out something only you know, and when a request leaves something open, Triage's instructions tell its agent to ask a person instead of guessing.
The task waits in the backlog. Notice that nothing happens to it there: no agent picks up a task until it reaches a station where agents work.
Point at the task and tick the box that appears beside it. A bar appears at the bottom of the board. Click Move to Triage.
Click Active. The task now stands at Triage, marked In progress: an agent is working on it. On the Runners page, your computer reads Running 1 of 1, one agent running out of the one it has room for.
Watch the agent work
Click the task's title to open it. Under Activity there is one row, for Triage. Each row is a run: one session in which an agent works on the task at a station. Click it.
At the top is what the agent was told, folded to its first few lines. Click it to see all of Triage's instructions, followed by your task. Below that, the agent's steps appear as it works, each labelled with what it did, such as Read or Thought. For the first few moments nothing appears, while your computer starts a fresh container for the agent.
When the agent finishes, its note appears under what it was told. The note ends with a question for you, such as who the new teammates are and what they will work on, and the run now reads Waiting for you.
If the agent passed the task on to Spec instead of asking, its note says why it thought nothing was left open. Open the task, choose Backlog in the station field under Properties, then choose Triage in the same field.
Go back to the board. The task is still at Triage, now marked Waiting for you. It stays there until you answer.
Answer the agent
Open Inbox. There is a new item, Write a welcome note for new teammates, in bold because you haven't read it. Open it. It shows the same run, ending with the agent's question.
In the box at the bottom that reads Reply…, enter:
Two designers, Sam and Priya, who will work on the mobile app. This task was only a test, so there's no need to pass it on.Press Enter.
The agent works again, and the item shows its steps as they happen. When they stop, its new note shows how it used your answer.
Close the task
That is all this tutorial needs from the task, so close it yourself before it goes any further down the line.
Open the task from the board. On the right, under Properties, the first field shows which station the task is at. The panel shows only when the window is wide enough.
Choose Completed from it. If an agent is still working on the task, Spotlight stops it. The task moves to Completed, the end of the line, and the Runners page shows your computer Idle again.
What you built
You created a workspace and set up your own computer to run its agents. You gave a task to Triage. Spotlight sent the work to your computer, which started a fresh container, and Claude Code worked on the task inside it using your Anthropic key. The agent asked you a question through the inbox, took your answer, and you closed the task by moving it to Completed.
From here:
- Make the factory yours puts the team's lines, which together make up its software factory, in a repository as code, points Delivery at your code and changes how Triage works.
- Lines, stations and tasks explains how a task moves from station to station, and who decides where it goes next.
- Install a host covers running agents on a server, and with coding tools other than Claude Code.