Create your first agent

By the end of this guide, you will have a valid Salambo project with instructions, a model, built-in tools, and deployment credentials.

Prerequisites

• A Salambo workspace
• Node.js 22 or later
• The Salambo CLI
• A scoped Salambo API key
• A provider key such as OPENAI_API_KEY

For this workflow, the Salambo key needs agents:read, agents:write, env_vars:read, env_vars:write, models:read, run:read, and run:write.

1. Create the project

salambo init support-agent
cd support-agent

The command clones the immutable starter version compatible with the installed CLI. It changes only the project name and agent slug; the template owns the runtime defaults.

2. Understand the minimum project

support-agent/
├── .pi/
│   ├── settings.json
│   ├── SYSTEM.md
│   ├── skills/
│   ├── prompts/
│   └── extensions/
├── sandbox/
│   └── workspace/
└── salambo.yaml

Salambo owns the model loop and run lifecycle. Your project supplies instructions, declared resources, extensions, workspace seed files, and deployment configuration.

3. Write the first instruction

Replace .pi/SYSTEM.md with:

# Customer support agent

Help support engineers investigate customer reports.

- Read available workspace files before answering.
- Separate confirmed facts from assumptions.
- Save investigation notes in `/workspace/notes.md`.
- Never include credentials or secret values in a response.

4. Select the model and tools

Edit .pi/settings.json:

{
  "defaultProvider": "openai",
  "defaultModel": "gpt-5.2",
  "defaultThinkingLevel": "medium"
}

The hosted runtime supplies Pi's read, write, edit, and bash tools. Tools discovered from .pi/extensions/ also start active. Shell utilities such as grep, find, and ls run through bash; they are not separate Pi tools.

5. Authenticate the CLI

salambo auth set --api-url https://YOUR_SALAMBO_HOST
salambo auth set --key "$SALAMBO_API_KEY"
salambo auth whoami

The CLI stores the selected profile locally. Do not commit API keys.

6. Provide the model credential

The generated salambo.yaml reads the provider key from your environment:

export OPENAI_API_KEY="YOUR_PROVIDER_KEY"

Secret values belong in the deployer's environment, never in salambo.yaml or agent instructions.

7. Validate the project

salambo doctor
salambo manifest --path . --json

doctor checks the hosted source-deployment contract, compiled manifest, managed packages, authentication, and declared secrets. manifest imports and validates agent resources and extension declarations without deploying them.

You now have a deployable agent project. Next, understand the project structure, then write production instructions.