Agentome GitHub
Contents

Getting started

This page takes you from nothing to a first finished task: you install Agentome, create the administrator, give agents a place to run, create an agent, put it on a project, file a task, watch the run and review what came back. It takes about half an hour.

The words used here, such as run, seat and policy, are explained in Concepts.

Before you start

You need:

Everything in this guide works on Free, without a license key, unless a step says otherwise.

1. Install the server

Pick one of the ways.

With the install script. On the server machine, run:

curl -fsSL https://agentome.ai/install.sh | sh

The script asks three things: the folder for the server (./agentome), the domain people open (for HTTPS with a Let's Encrypt certificate; Enter keeps the server on this machine only), and whether people's agents run here, in places on the server. With places, it turns gVisor on when Docker has it. It then downloads the release's compose.yaml, writes .env, pulls the images from Docker Hub and starts everything. When the server is healthy it prints a line like this:

Agentome is running. Open http://localhost:3000/setup to create the administrator, with the setup code <code>

The script also puts an agentome command on the machine (in ~/.local/bin, or /usr/local/bin for root), which runs this server from any folder: agentome status, agentome update, agentome backup, agentome logs, agentome setup-code; agentome help lists them all.

Without a terminal, give the answers as flags:

curl -fsSL https://agentome.ai/install.sh | sh -s -- --domain agentome.example.com --places
curl -fsSL https://agentome.ai/install.sh | sh -s -- --help

Keep the setup code for step 2.

With Node.js. On a machine with Node.js 20 or later, the agentome package on npm asks the same questions and installs the same release:

npx agentome install

It does not turn gVisor on for places or put the agentome command on the machine: use the script for a server with places, or install the package with npm install -g agentome to have the command.

From a checkout. If the machine cannot reach Docker Hub, or you want to build from source:

git clone https://github.com/agentome-ai/agentome.git
cd agentome
docker compose up -d --build
docker compose exec app agentome setup-code

The last command prints the setup code. The server answers at http://localhost:3000.

If people will reach the server by any other address than http://localhost:3000, set AGENTOME_PUBLIC_URL in .env before you go on, then run docker compose up -d. To connect other people's computers you also need HTTPS: see HTTPS with the proxy profile. All settings are listed in CONFIG.md.

2. Run the first-run setup

  1. Open /setup on the server's address, for example http://localhost:3000/setup.
  2. In Setup code, paste the code from step 1. If you lost it, run docker compose exec app agentome setup-code in the folder that holds compose.yaml, or look in the server's log with docker compose logs app.
  3. In Company name, enter your company's name, such as Acme.
  4. Under Administrator, fill in Your name, Email, Password (at least 12 characters) and Confirm password.
  5. Click Create the administrator account.

The Set up Agentome page with the setup code, the company name and the administrator's name, email and password

You are signed in as the first administrator and land on the Dashboard. The sidebar holds the work (Dashboard, Approvals, Tasks, Runs) and, under Workforce, Agents, Teams, Projects and Library. Admin and Help are at its foot. Press ⌘K (Ctrl K on Windows and Linux) anywhere to jump to a page.

The Agentome window: the sidebar on the left and the empty Dashboard on the right

To bring in colleagues, open Admin → People, click Invite someone and send them the invitation link. More in Administration.

3. Give agents a place to run

An agent needs somewhere to run. Choose one:

Option A: make your place on the server

  1. Turn places on, once, on the server machine: in the folder that holds compose.yaml, put AGENTOME_PLACE_LAUNCHER_URL=http://place-launcher:8080 in .env and run docker compose --profile places up -d. On Kubernetes, take the places component of deploy/kubernetes. More in Places on the server.
  2. In Agentome, open Admin → Computers. Under Your place on the server, click Make my place. It takes a minute the first time, while the place installs Claude Code.
  3. Click Open terminal. In the terminal, run claude and sign in with your Claude subscription: open the link it shows in your browser, then paste the code back. For Codex, run codex login --device-auth and enter its code in your browser.
  4. Close the terminal. Your agents now run in your place whenever you have Agentome open and in use.

Option B: connect your computer

  1. On the computer you want to connect, check that Claude Code is installed and signed in: run claude, and sign in with your Claude subscription if it asks. Node.js 20 or later must be installed too (node -v).

  2. In Agentome, open Admin → Computers and click Connect a computer.

  3. The dialog shows a one-time code and a command. Click Copy command. The code works once, for ten minutes; the dialog says until when.

  4. Paste the command into a terminal on your computer and run it. It looks like this:

    curl -fsSL https://agentome.example.com/connect | sh -s -- K7QX-M2PH

    The script checks for Node.js and Claude Code, downloads the worker into ~/.agentome/bin, checks it against its checksum, connects the computer and starts the worker as a background service of your login session.

  5. Click Done in the dialog. Your computer appears in the list as Online, with Ready for runs under Activity.

The Connect a computer dialog with a one-time code, the command to copy and the time until it expires

If the server runs from source with pnpm dev, the command is a pnpm command instead and the dialog says Run it in a checkout of the repository. Everything about computers, including what to do when a computer shows Offline or Claude Code is not signed in, is in Where agents run.

Option C: add a model connection for agents on the server

Needs a license key. An admin pastes one in Admin → License.

  1. Open Admin → Models and click New connection.

  2. Enter a name, such as "Anthropic for agents".

  3. Pick the kind: Anthropic (Claude models, for Claude Code), OpenAI (GPT models, for Codex) or Gateway (LiteLLM, OpenRouter or another). For a gateway, enter its address.

  4. Paste the API key. Use a key made for agents, with a spending limit at the provider.

  5. Click Connect. Agentome lists the connection's models to check the key, and keeps the key encrypted.

  6. Start the server seat. Open Admin → Computers, click Connect a computer, and copy the second command, under Or connect the server seat with it. On the server machine, in the folder that holds compose.yaml, run it and then start the seat:

    docker compose run --rm seat connect <code> --server http://app:3000
    docker compose --profile server-seat up -d

The New model connection dialog with the connection's name, its kind, its address and the API key

The details, including the seat's first start and its limits, are in The server seat.

4. Create a project

Every task is filed in a project. Any signed-in person can create one; its maker and the admins can change it.

  1. Open Projects and click New project.
  2. Name it after the work, not the repository, such as "Payments".
  3. Click Create project. The project's page opens.

On that page you can add a Description and Goals, which agents read with each task. Repositories are optional for a first task:

A project page with its description, its agents, its repositories and its knowledge

5. Create an agent

  1. Open Agents and click New agent.
  2. Pick a role template, or Blank agent to write the instructions yourself.
  3. Check the Name and Role title, such as "Payments backend" and "Backend developer".
  4. Click Create agent. The agent's editor opens.

The New agent dialog with role templates, the agent's name and its role title

The editor is one page: its sections are listed on the left, and the agent's sheet, a summary of what it is, stays on the right. For a first task, look at three sections:

Click Save changes at the top when you are done. The other sections, such as Skills, Memory and Budget, are described in Agents.

The agent editor: sections on the left, the Engine & model section in the middle, the agent's sheet on the right

6. Put the agent on the project

Only a project's agents work on its tasks.

  1. Open Projects and then your project.
  2. In the Agents section, click the add button and pick your agent from the list (Add agent).

The agent is listed under Agents, and its sheet in the editor shows the project under Works on. You can put only your own agents on a project you made; an admin can put any agent on any project.

7. File a first task

  1. Open Tasks and click New task.
  2. Write a Task title, such as "Add a health check endpoint".
  3. Describe what to do below it. The description is Markdown and goes to the agent as it is.
  4. Under the description, choose:
    • the project, in Choose a project;
    • the agent, in Choose an agent or a team;
    • where it works. The chip opens a list: a repository of the project, a folder On your computer (type its path, such as ~/code/app), or No repository, which gives the run a new empty folder each time.
  5. Leave Run now on. The line next to it says where the run goes, such as "Runs on Ann's MacBook now", or that it waits for a computer.
  6. Click Create and run. Press ⌘↵ (Ctrl Enter) to do the same from the keyboard.

The New task dialog with a title, a description, the project, the agent, the folder it works in and Run now

With Run now off, the button reads Create task, and the task waits until you click Run on its page.

8. Watch the run

After Create and run, the run's page opens and follows the run live.

A live run: the agent's plan with one step in progress, and the transcript below it

While the run is queued, the transcript says "Waiting for a computer to pick this run up." It starts when your computer, or the server seat, takes it.

If a tool call needs your approval, the run shows Waiting for you with Approve, and the call also waits in Approvals in the sidebar. Open it, read what the agent wants to do and click Approve or Deny. More in Approvals and control.

Approvals: an agent asks to open a pull request, with the run so far and Approve or Deny

To stop a run, click Cancel run and confirm. What the run did so far stays in the transcript.

9. Review the result

When the run ends as Done, its page leads with the agent's answer, and the right column lists the Artifacts: a Report, a Branch and, when the agent opened one, a Merge or pull request. Cost shows what the run cost, By model.

A finished run: the agent's answer, its artifacts and its cost

The task moves to In review, and the Dashboard lists it under Ready for your review. Open the task (the Task link on the run, or Tasks, tab In review):

  1. Read the report and look at the changes. If the task worked in a folder on your computer, the agent's commits are in that repository as a new branch, agentome/<run id>; your own branches are left as they were.
  2. If it is what you wanted, click Mark as done.
  3. If not, write to the agent in the comment field at the bottom ("Write to Payments backend: what to change, what you found") and click Comment and run. The next run reads your comment. Comment alone saves it for the next run, and Run again starts one without a comment.

A task in review: its description, the run's report and the comment field

That is your first finished task.

Where to go next

Edit this page on GitHub