Setup Guide

This guide covers the setup that every part of Chalk shares: installing the CLI, creating a project, and getting the credentials and permissions your code needs. It ends with the first steps for features and resolvers, sandboxes, functions and scaling groups, evaluations, and notebooks.

​

Installing the CLI and creating your project

1. If you don’t already have a GitHub repository where you will store your Chalk code, create one. Then, pick a local directory in which to work on Chalk code, and clone the GitHub repository there. Then cd inside of the directory.
2. Install the Chalk command line tool. The Chalk CLI allows you to create, update, and manage your feature pipelines directly from your terminal

curl -s -L https://api.chalk.ai/install.sh | sh

3. Log in by typing chalk login. If your organization uses an isolated deployment with its own API host, pass that host with the --api-host flag. Type y when prompted and log in through the browser.

4. Run chalk init from your repository root, and answer its prompts:

• If you have access to more than one project, choose the project to use.
• chalk init requires uv. If uv is not installed, choose to install it when chalk init asks.
• Choose the coding agent you use, or choose Skip.

When chalk init finishes, your project dependencies are installed in .venv. For the files and settings it creates, see What chalk init sets up.

5. Install the Chalk plugin for your editor.

You now have a virtual environment with chalkpy and chalkcompute installed, and a project directory to build on. To run a Python file in that environment, use uv run, for example uv run python main.py. The CLI finds the chalkpy in .venv on its own unless another chalkpy is on your PATH.

​

What chalk init sets up

chalk init uses the project from your login, as reported by chalk whoami. If you are not logged in, it asks for a project name. It then adds chalkcompute and chalkpy to pyproject.toml and runs uv sync, which creates a virtual environment in .venv and installs them. uv uses an installed Python that matches requires-python in pyproject.toml, and downloads one if none matches. If the installation fails, chalk init exits with an error.

If chalk init installs uv, uv is available in new terminals. To run uv commands yourself, open a new terminal.

chalk init creates the following files and directories:

root_directory/
├── .chalkignore
├── .gitignore
├── .helix/
│   └── languages.toml
├── .venv/
├── .vscode/
│   ├── extensions.json
│   └── settings.json
├── .zed/
│   └── settings.json
├── chalk.yaml
├── pyproject.toml
├── README.md
└── uv.lock

chalk.yaml stores configuration information about your project:

project: {YOUR_PROJECT_NAME}
environments:
  default:
    runtime: python312
    requirements: pyproject.toml

pyproject.toml lists your project dependencies. It also contains [tool.pyright], [tool.mypy], and [tool.ty.rules] settings that stop those type checkers from reporting diagnostics on Chalk code. The .vscode, .zed, and .helix files configure those editors for the Chalk editor plugin. .chalkignore works like a .gitignore file: files that match its patterns are excluded from deploys when you run chalk apply.

chalk init does not install chalkdf, the package for Chalk DataFrames. To use Chalk DataFrames, add it to your project:

$ uv add chalkdf

If you choose a coding agent, chalk init writes an instruction file with Chalk-specific context, installs Chalk’s agent skills in the project, and registers the Chalk MCP server. For Claude Code, it creates CLAUDE.md and installs the skills in .claude/skills/. For Codex, it creates AGENTS.md and installs the skills in .agents/skills/. The MCP server is registered for your user, so it is available in every project, and it replaces an existing MCP server named chalk.

chalk init does not overwrite files that already exist. In an existing pyproject.toml, it adds the packages and type checker settings that are missing; the file must have a [project] table. To print Chalk’s recommended settings for existing pyproject.toml and editor files so that you can merge them yourself, run chalk init --show-settings.

Outside an interactive terminal, such as in a script, chalk init does not prompt and skips the coding-agent step. If you are not logged in, create chalk.yaml before you run it there. For the full behavior, see the chalk init reference.

​

Logins and environments

chalk login saves a token in ~/.chalk.yml, or in $XDG_CONFIG_HOME/.chalk.yml when XDG_CONFIG_HOME is set. It saves the token for the folder you run it in. The first token you save is also your default token.

When you run Chalk code, Chalk looks for a token saved for your project:

• The CLI uses the token saved for the folder you run it in, or the default token if there is none.
• chalkpy and chalkcompute use the token saved for the folder that contains your chalk.yaml, or the default token if there is none.

To use one login for a whole project, run chalk login in the folder that contains chalk.yaml.

Each token has an active environment. To change it, run chalk environment with the name or ID of the environment:

$ chalk environment <environment>

To see which project and environment you are using, run chalk whoami.

​

Credentials for code that runs elsewhere

Code that runs on the machine where you ran chalk login, including a local Jupyter notebook, uses that login and needs no other credentials.

Code that runs where you cannot log in through a browser, such as a CI job, a hosted notebook like Hex or Google Colab, or a coding agent in a sandbox, needs a service token instead:

1. In the Chalk dashboard, go to Settings > Access tokens and create a token with the permissions that the code needs. The dashboard shows the token’s Client ID and Secret Key once. For details, see Creating a service token in the dashboard.
2. Give the code the token in one of two ways:

   • Set these environment variables where the code runs:

     Variable	Value
     CHALK_CLIENT_ID	The token’s Client ID
     CHALK_CLIENT_SECRET	The token’s Secret Key
     CHALK_API_SERVER	Your API server, if it is not https://api.chalk.ai
     CHALK_ENVIRONMENT	The name or ID of the environment to use

   • Log the CLI in with the token, using the CLI Login command that the dashboard shows with it:

     $ chalk login --client-id <client-id> --client-secret <secret-key>
     

chalkpy and chalkcompute use the environment variables before any token that chalk login saved. For notebook services, see Authentication for External Notebooks. For CI, see GitHub Actions.

​

Permissions

Your role in an environment decides what you can do there. A service token has the permissions that were selected when it was created.

The task in an evaluation is a deployed function. A Data Scientist or Developer can run an evaluation of a task that someone with deploy.create has deployed.

A custom role or a service token can include any of these permissions.

​

Start building

Each part of Chalk has its own first steps.

​

Features and resolvers

To connect your data sources and define, deploy, and query your first features, see the Quick Start.

​

Sandboxes, functions, and scaling groups

You create sandboxes, functions, and scaling groups in Python with chalkcompute, which chalk init installed. You do not deploy them with chalk apply. To check that your login and environment work, save this file as check_sandbox.py. It starts a sandbox, runs a command in it, and shuts the sandbox down:

import chalkcompute

if __name__ == "__main__":
    sandbox = chalkcompute.Sandbox(
        image=chalkcompute.Image.debian_slim("3.12"),
        cpu="1",
        memory="2Gi",
    ).run()
    print(sandbox.exec("echo", "ok").stdout_text)
    sandbox.terminate()

Run it with uv run, which uses the virtual environment that chalk init created:

$ uv run python check_sandbox.py
ok

When Chalk deploys a function or a scaling group, it imports the whole file that defines it. Put code that creates or runs anything under if __name__ == "__main__": so that it does not run again when the file is imported.

To continue, see the Sandboxes quick start, Functions, or Scaling Groups.

​

Evaluations

Evaluations also use chalkcompute. You define the task and scorers in Python, deploy the task as a function, and run the evaluation from Python. To run your first evaluation, see the Evaluations quick start.

​

Notebooks

Hosted notebooks run in the Chalk dashboard, so there is nothing to install. To work with them from a terminal, use chalk notebook. A notebook cell does not use the --branch flag that you pass to the CLI. To query a branch from a cell, pass the branch to the client:

from chalk.client import ChalkClient

client = ChalkClient(branch="my-branch")

External notebooks, such as Jupyter or Hex, use chalkpy with a login or a service token. To set one up, see External Notebooks.

​

One-time setup for admins

Chalk turns on Sandboxes, Functions, Scaling Groups, Evaluations, the Model Gateway, the MCP Gateway, and the Model Registry for each environment. If they are not turned on in your environment, contact Chalk support.

Chalk deploys the Model Gateway when you add its first provider connection, and the MCP Gateway when you register its first MCP server. Both steps require the deploy.create permission. You do not add either gateway to a resource group yourself.

The rest of the setup in this table is needed only in the situations it describes:

On your own cluster, Chalk creates a default host pool the first time you start a sandbox, so you can start sandboxes before you configure host pools.

​

Troubleshooting

​

No Chalk credentials found

chalkcompute raises this error when it finds neither the CHALK_CLIENT_ID and CHALK_CLIENT_SECRET environment variables nor a token saved by chalk login. Run chalk login in the folder that contains chalk.yaml, or set the environment variables.

​

Feature flag is not enabled

A request fails with feature flag 'scaling_groups_enabled' is not enabled or feature flag 'evaluations_enabled' is not enabled when Sandboxes, Functions, Scaling Groups, or Evaluations are not turned on in the environment. Contact Chalk support to turn them on.

​

Commands use the wrong environment

Run chalk whoami in the folder you are working in. If it shows the wrong environment, the folder may have its own token from an earlier chalk login, or CHALK_ENVIRONMENT may be set. Run chalk environment to change the environment, or unset CHALK_ENVIRONMENT.

​

A notebook cell does not see your branch

Pass the branch to the client in the cell, with ChalkClient(branch="my-branch"). The cell does not use the CLI’s --branch flag.