# Quick Start > **Warning** > > Project Neo is currently in [Technical Preview](../../../../a-z/squirro-glossary.md#term-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](overview.md#neo-agent-config-overview) page. Before you begin, make sure you have everything on the [Prerequisites](prerequisites.md#neo-agent-config-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: ```text 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: ```text cd my-agent-configuration-project ``` Finally, initialize the directory: ```text 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: ```text 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](cli-reference.md#neo-agent-config-rollback) section. ## Write the Three Files Create the project manifest, one model, and one agent. `project.yaml` sets the project-wide default model: ```text 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: ```text 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](resource-reference.md#neo-agent-config-register-handle) section. This example uses Anthropic. For the full list of supported providers and how to authenticate to each, see the [Resource Reference](resource-reference.md#neo-agent-config-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: ```text metadata: id: claude-opus ``` is the same as this: ```text 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: ```text --- 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](authoring-agents.md#neo-agent-config-authoring) 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: ```text genai lint ``` A successful run reports what it checked: ```text 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](cli-reference.md#neo-agent-config-cli) 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: ```text 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](troubleshooting.md#neo-agent-config-troubleshooting-rejected) 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: ```text genai deploy ``` A successful deploy prints a receipt: ```text 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: ```text 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](resource-reference.md#neo-agent-config-register-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](authoring-agents.md#neo-agent-config-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`: ```text genai status ``` It reports the configuration currently live, without transferring it: ```text 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](overview.md#neo-agent-config-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](cli-reference.md#neo-agent-config-cli) 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](authoring-agents.md#neo-agent-config-authoring) page. - For the full set of resource kinds and their fields, see the [Resource Reference](resource-reference.md#neo-agent-config-resource-reference) page. - For the complete catalog of preference paths, with the type and default of each, see the [Preference Reference](preference-reference.md#neo-agent-config-preference-reference) page. - For every `genai` command and flag, see the [CLI Reference](cli-reference.md#neo-agent-config-cli) page.