Set up Sikaru
Work through these steps in order. Stop at the first one that already passes.
1. Install the CLI
sikaru decision --help >/dev/null 2>&1 && echo ok
If that fails, install or upgrade:
curl -fsSL https://app.sikaru.ai/install.sh | sh
With Node.js 20+ (any platform, including Windows): npm install -g @aadi-labs/sikaru-cli.
Older builds lack the decision and credits groups. If sikaru decision --help
still fails after installing, the newer CLI may be on a different PATH entry.
Check which -a sikaru. If the installer doesn't work, tell the user and point them to
https://github.com/aadi-labs/sikaru-clients. Don't build or download binaries from
anywhere else.
2. Sign up or sign in
One flow covers both. A new user gets an organization named after them (for example "Ada's Team") and a default project. An existing user lands in their organization. The user approves in their own browser: never type their email, password or payment details into a form for them.
With the CLI (preferred)
sikaru login --no-browser
The command prints a one-time code and a verification URL on stderr. It then waits until the user approves or the code expires.
- In an agent shell, run it in the background so your tool call doesn't time out. Read the code and URL from its output, give both to the user, and wait for the command to exit 0. If the code expires, run it again.
- On success the CLI saves the default project and prints
Using project .... No project ID needs to be copied from the dashboard. - At an interactive terminal, plain
sikaru loginopens the browser for the user. Any command run there while signed out starts sign-in automatically. Without a terminal, a signed-out command fails with an auth error, so sign in first. - If
SIKARU_API_KEYis set, it overrides the sign-in. Unset it for personal access. sikaru login --with-tokenreads a token the user pastes from standard input. Don't put the token on the command line, where it lands in shell history.
Without the CLI (agent registration)
Follow https://sikaru.ai/auth.md with the user's email. It registers you, has the user
approve, and gives you a short-lived access token for Authorization: Bearer.
- The approval link expires after about 5 minutes. Give it to the user immediately, and mint a new attempt if they're too late.
- The user reads a code like
ABCD-EFGHoff the page. If completing the claim says the code is invalid, retry once without the hyphen (ABCDEFGH). - A new user's first call, whichever it is, creates their organization and default
project.
GET https://api.sikaru.ai/v1/projectsreturnsdefaultProjectId. - Model and System One calls without a
Sikaru-Projectheader use the default project. Send the header to use another one.
3. Choose a different project (optional)
Sign-in already chose the default project. To switch:
sikaru config set project PROJECT_ID
sikaru config show
Commands with -p/--project use the saved project, or SIKARU_PROJECT if that is
set. Signed-in inference and decision calls bill the saved project, else the
organization's default project.
4. Check access
sikaru doctor
It checks the credential, the project and the workspace without starting a run.
| Status | Meaning |
|---|---|
| 401 | The credential is missing, invalid, or pointed at the wrong endpoint. Sign in again. |
| 403 | The credential can't do that operation in this project. Use a key with that permission. |
| 404 | Wrong project or resource ID, or it isn't visible to this caller. |
Don't fix an access failure by changing IDs or retrying.
5. Get an API key for code, servers and CI
SDKs and automation use a project API key, not the CLI sign-in. Install the published SDK for the project's language:
pip install sikaru-sdk # or: uv add sikaru-sdk; import sikaru_sdk
npm install @aadi-labs/sikaru-sdk # TypeScript, server-side code only
The user creates the key in the dashboard (https://app.sikaru.ai) for the project. Store it in the environment or a secret manager:
export SIKARU_API_KEY=... # user pastes it; never echo it back
export SIKARU_PROJECT=PROJECT_ID
Grant only the permissions the integration needs:
| Task | Permission |
|---|---|
| List agents and read runs and trajectories | runs:read |
| Create an agent | managed_agents:write |
| Start a run | runs:create |
| Read run events | events:read |
| Send tool results or approvals | tool_results:write |
| Manage connections | tool_providers:write |
| Make release decisions | harness:write |
Keep the key on the backend. A browser or mobile app calls your backend, and the backend calls Sikaru.
6. Add credits (only when asked or when a run pauses for funding)
sikaru agent run exits with code 5 when a run is paused for funding. Check the
balance first:
sikaru credits balance -o json # {"state", "availableUsd", "topUpMaxUsd"}
state |
What to do |
|---|---|
no_card |
No credits yet. Top up from an agent wallet (the first paid top-up opens the organization's credit account), or ask the user to save a card in Billing at https://app.sikaru.ai, which adds a one-time $5 starting credit. Don't enter card details for them. |
complimentary |
Usage is covered. No credits needed. |
ready with topUpMaxUsd null |
An organization admin turned agent top-ups off. Ask the user to add credits in Billing. |
ready |
Top up from an agent wallet, up to topUpMaxUsd. |
To add credits from an agent wallet:
sikaru credits add --amount 20 -o json # creates an offer; prints payUrl and id
sikaru credits status TOP_UP_ID # "credited" once the payment lands
The minimum is 5 US dollars. Confirm the amount with the user before you create an
offer. Give them the pay URL, or pay it only with a wallet they explicitly approved
for this payment. Don't say credits were added until credits status reports
credited. Then resume the paused run with the next command from its result.
Docs: https://sikaru.ai/auth.md, https://docs.sikaru.ai/get-started/authentication.md, https://docs.sikaru.ai/sdks-and-cli/cli-automation.md, https://docs.sikaru.ai/sdks-and-cli/credits.md