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. Use the first tab on macOS, Linux, or Git Bash on Windows, and the second in Windows PowerShell.

curl -s -L https://api.chalk.ai/install.sh | sh
export PATH="$HOME/.chalk/bin:$PATH"

The installer adds chalk to your PATH in your shell profile, which new terminals read. The second line adds it to the terminal you are using now. In PowerShell, the installer adds chalk to your user Path, and the second line adds it to the current terminal.

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.

chalk init installs chalkcompute on these platforms, with Python 3.11 through 3.14:

• macOS on Apple silicon (arm64) and Intel (x86_64)
• Linux on x86_64 and aarch64, with glibc 2.28 or later
• Windows on x86_64

On other platforms, chalk init does not install chalkcompute. Alpine Linux and other musl-based distributions are not supported.

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.

​

Starting in a Chalk Serverless environment

A new Chalk Serverless environment has Sandboxes, Functions, Scaling Groups, Evaluations (Public Preview), Notebooks, the Model Gateway, the MCP Gateway, and the Model Registry enabled. It includes a small online store, and it has no offline store or data sources until you connect them.

Before you connect any stores or data sources, you can:

• Deploy features and resolvers with chalk apply and run online queries
• Run offline queries that compute features from the inputs you pass
• Run sandboxes and call functions
• Run evaluations (Public Preview)

An offline query that reads stored feature values needs an offline store. To connect your stores and data sources, see Connecting your stores and data sources.

The Model Gateway routes requests after you add a provider connection with your API key for that provider. See Model Gateway.

​

Logins and environments

chalk login saves your token to ~/.chalk.yml, or to $XDG_CONFIG_HOME/.chalk.yml when XDG_CONFIG_HOME is set. Your first login is used everywhere. A later login applies only in the folder you ran it from. To change the token used everywhere, delete the default: entry in ~/.chalk.yml and run chalk login again.

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, listed in Permissions for a service token. 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. The Permissions page lists every permission you can select and the built-in roles that include each one.

​

Permissions for a service token

A service token has only the permissions selected when it was created. Every built-in role includes deploy.read, but a service token needs it selected: the SDK uses it to check the status of sandboxes, functions, scaling groups, and image builds after it creates them.

A token that does more than one of these needs the permissions from each row. To give a token narrower access, such as sandbox.connect to run commands in sandboxes without deploy.redeploy, select permissions from the Permissions page.

​

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. notebook.write applies only to hosted notebooks. An external notebook needs the permissions for what it runs, such as query.online or query.offline for queries.

​

One-time setup for admins

Chalk enables Sandboxes, Functions, Scaling Groups, Evaluations, the Model Gateway, the MCP Gateway, and the Model Registry for each environment. If they are not enabled 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 module named ‘chalkcompute’

chalk init installs chalkcompute and chalkpy in the project’s .venv. Running a file with python uses a Python that does not have them, and the import fails with ModuleNotFoundError: No module named 'chalkcompute'. Run the file with uv run:

$ uv run python main.py

You can also activate the environment once with source .venv/bin/activate, then run files with python. In Git Bash on Windows, run source .venv/Scripts/activate. In PowerShell, run .venv\Scripts\activate, which runs a script and fails under Windows’ default execution policy unless you first run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned; uv run works without either.

​

No offline store was configured

An offline query that reads stored feature values fails with The plan requires offline storage, but no offline store was configured when the environment has no offline store. A new Chalk Serverless environment has no offline store until you connect one. See Connecting your stores and data sources. An offline query that computes features from the inputs you pass, with recompute_features=True, does not need an offline store.

​

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 enabled in the environment. Contact Chalk support to enable them.

​

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.