Quick Start#
Warning
Project Neo is currently in Technical Preview. Features described in this section may change before general availability.
This walkthrough takes you from an empty directory to a deployed, queryable configuration: three files, two commands, and one query.
For the concepts behind each step, see the Overview page.
Before you begin, make sure you have everything on the Prerequisites page.
Scaffold the Directory#
Start by creating an empty directory for your agent configuration project, moving into it, and initializing it. This walkthrough works through the three steps one at a time.
Run the commands in the terminal of your choice. The genai CLI runs anywhere you have Python 3.11 or later, and the project directory lives locally on your own machine. You author and validate it there, and only the genai deploy step later sends the configuration to your Squirro instance.
First, create the directory:
mkdir my-agent-configuration-project
my-agent-configuration-project is only a placeholder. Replace it with a name that reflects what you are working on, and follow any naming conventions your team already uses for repositories and projects.
Next, move into the new directory using the following command:
cd my-agent-configuration-project
Finally, initialize the directory:
genai init
genai init prepares the directory for deployment. On a terminal it prompts for the cluster URL and the project ID, writes local configuration so subsequent commands know where to deploy, and authenticates you to the cluster. If you already have the values, pass them to skip the prompts:
genai init . --cluster https://squirro-demo.example.com --project Xy7QmN2pR9sT4vWz1AbC3D
Squirro recommends putting the project folder under version control now, before you author any files. Initialize a repository in the directory, for example with git init, so every configuration you deploy is recoverable and you can attach the commit hash to each deploy. This matters because there is no way to restore a past configuration from the platform: rolling back means redeploying your own files, as described in the Roll Back a Deployment section.
Write the Three Files#
Create the project manifest, one model, and one agent.
project.yaml sets the project-wide default model:
kind: Project
schema: v1
title: My first project
prefers:
inference.model: claude-opus
Here, the inference.model preference in the prefers block sets the default model, which applies unless an agent, a user, or a request selects a different one. inference.model is a single flat key, not a nested inference block with a model field. The title is an optional display label shown to users in the Chat interface.
models/claude-opus.yaml declares one model:
kind: Model
schema: v1
metadata:
id: claude-opus
provider: anthropic
model_name: claude-opus-4-8
auth:
type: bearer
secret: anthropic_token
Two names appear here and they are not the same thing. metadata.id is a name you choose, and it is what inference.model and every other reference points at. model_name is the identifier the provider publishes, and it has to match what the provider expects exactly. Nothing requires the two to resemble each other, so the examples across this documentation use whichever model suits the point being made, and your own project can use any identifiers you like.
The secret: anthropic_token is a handle: a name bound to an actual API key on the cluster. You write the name. You never write the key. For more information, see the Registering a Handle section.
This example uses Anthropic. For the full list of supported providers and how to authenticate to each, see the Resource Reference page.
The metadata block here is written in expanded form, with id on its own indented line. YAML also has a compact inline form that puts the mapping on a single line inside braces, so this:
metadata:
id: claude-opus
is the same as this:
metadata: { id: claude-opus }
The examples in this documentation use the expanded form. Use whichever you find easier to read.
agents/assistant.md is the agent itself:
---
kind: Agent
schema: v1
metadata:
id: assistant
title: Assistant
entrypoint: true
---
You are a helpful assistant for the team knowledge base.
**Structure every answer in three parts:**
- A one-sentence summary.
- The detailed answer, with the key terms in **bold**.
- The sources you relied on, as a bulleted list.
## Tone
Keep responses clear and concise. When you are unsure, say so rather than guessing.
The block between the --- lines at the top is the envelope. The markdown body below it becomes the agent instructions, the prose the model runs as its system prompt. entrypoint: true makes the agent selectable, so it appears in the conversation picker. title is the display name shown there. When you omit it, the picker falls back to the agent id, which is assistant here.
The Squirro instance passes the body to the model as written, so you can use markdown, such as bold, bulleted lists, and headings, to structure and emphasize the instructions, as that example does. For the full guidance on writing instructions, including model-specific text, see the Authoring Agents page.
Validate#
With the three files in place, check them before you deploy. genai lint runs offline, with no network and no credentials, and catches everything that can be verified without the cluster: envelope shape, references to resources that do not exist, and disagreeing pins.
Run it from the project directory:
genai lint
A successful run reports what it checked:
OK (1 resources, 1 agents)
On a larger project, genai lint can also print advisory lines above that OK. They point out a configuration that deploys and runs but is probably not what you meant, and they do not stop a deploy. For what they cover, see the genai lint section on the CLI Reference page.
If anything is wrong, genai lint reports every problem it found instead, each on its own line, so you can fix them in one pass rather than one at a time. For example:
publish rejected:
- project.prefers.inference.model: unknown Model 'claude-opus-4'
- agents.assistant.prefers.trait.style: unknown TraitDimension 'style'
- agents.assistant.pins.source.documents.enabled: conflicts with project pin: agent pins to true, project pins to false
Each line names where the problem is and what is wrong: a preference that points at a model, trait, or other resource that does not exist, or a pin that disagrees with another. Fix the files and run genai lint again until it reports OK. For how to read this output in detail, and for the common failures and their fixes, see the Reading a Publish-Rejected Result section.
Because the check needs nothing but your files, it also makes a good pre-merge step if you keep the project in continuous integration.
Deploy#
Once genai lint reports OK, deploy the configuration to your Squirro instance. genai deploy sends the files to the cluster, where the server re-runs every check, including the ones that need the cluster and cannot run offline, such as confirming each credential handle resolves. Only if every check passes does the configuration become the live snapshot for the Squirro project. Otherwise the deploy is rejected and the previous configuration stays in place.
Run it from the project directory:
genai deploy
A successful deploy prints a receipt:
deployed: sha256:4a3f1c...
at: 2026-05-14T11:32:00+00:00
labels: (none)
The deployed hash identifies this exact configuration, at is when it went live, and labels are any metadata you attached to the deploy.
If a check fails, the server rejects the whole deploy and lists what went wrong, in the same form as genai lint. A common failure at this stage is a credential handle that has no value registered on the cluster, because that is one of the checks genai lint cannot run offline:
publish rejected:
- Model.claude-opus.auth.secret: handle 'anthropic_token' not found in secret store
The previous configuration stays live until a deploy passes every check. Register the handle, as described in the Registering a Handle section, then run genai deploy again.
The configuration is now live. A user picking Assistant in the Chat interface gets an agent backed by the model you declared, running your instructions. For what a deployed agent looks like to a user, see the How an Agent Appears in Chat section.
Confirm What Is Live#
genai deploy already told you the deploy succeeded. To ask the Squirro project itself what it is running, use genai status:
genai status
It reports the configuration currently live, without transferring it:
project: Xy7QmN2pR9sT4vWz1AbC3D
cluster: https://squirro-demo.example.com
deployed: 2026-05-14T11:32:00+00:00
by: alice@example.com
hash: sha256:4a3f1c...
labels: (none)
The hash matches the one your deploy printed, which confirms that what is live is the configuration you just sent. Run genai status any time you need to know what a project is running, and who deployed it.
From here, the project resolves each setting per request, walking the request, the user, the selected agent, and the project in that order. Your project.yaml prefers claude-opus and nothing else sets a model, so every request resolves to claude-opus until an agent, a user, or a request says otherwise. For the full resolution model, see the Overview page.
Note
The genai explain command reports that walk setting by setting, which is useful while you are reasoning about a configuration. During Technical Preview it depends on a route that a Squirro instance does not serve, so it does not answer against a deployed project. See the genai explain section on the CLI Reference page before you rely on it.
Next Steps#
That is a complete author, validate, and deploy cycle. From here:
To shape agent behavior with preferences, constraints, and pins, and to write effective instructions, see the Authoring Agents page.
For the full set of resource kinds and their fields, see the Resource Reference page.
For the complete catalog of preference paths, with the type and default of each, see the Preference Reference page.
For every
genaicommand and flag, see the CLI Reference page.