Chalk

Docs · Onboarding

Getting started

Try Chalk on your own machine first — no root, no production data directory. If you already have a hosted tenant, skip to the first-admin walkthrough below.

Run a local trial

Install the binary, create a directory you own, and start the console. This is the same first-user path as the README.

curl -fsSL https://raw.githubusercontent.com/usechalk/chalk/main/install.sh | sh
mkdir chalk-trial && cd chalk-trial
chalk init --data-dir . && chalk serve --port 8080

Then open http://localhost:8080. Windows: download the .exe from Releases.

Production installs can omit --data-dir .; the default data directory is /var/lib/chalk on Linux and needs root. See the deployment guide in the repository.

Already on hosted Chalk? Steps 1–5 and 8 apply to every tenant, including the free hosted tier — connecting your SIS is how Chalk learns your roster in the first place. Steps 6 and 7 hand that roster back out, through the OneRoster API and SAML SSO, and those are the Full stack tier if we host you — or included at no cost if you self-host. Both are marked.

First-admin walkthrough (hosted tenant)

1

You just clicked the verification email — now what?

Clicking the verification link finalizes your tenant. You land on the admin console at your tenant subdomain (e.g. yourdistrict.usechalk.xyz). The link is single-use; if it expires, request a new one from the sign-in page.

2

Set your admin password

The first thing the console asks for is a password for your administrator account. We use Argon2id with sensible defaults — pick something memorable but strong. You can enable SAML SSO later (step 7) and stop using a local password entirely.

3

Tour the admin dashboard

The dashboard shows tenant health at a glance: last sync, user counts, recent audit events. The left nav is grouped by job — Sync, Users, Google Sync, Identity, SSO Partners, Webhooks, Settings — with audit log and API tokens under Tools.

See the full feature inventory →
4

Configure your first SIS sync

From Sync → Connectors, choose your SIS. Chalk ships with first-class connectors for PowerSchool, Skyward, Infinite Campus, and any OneRoster CSV source. Each connector asks for the credentials specific to that SIS (OAuth client/secret, base URL, plugin keys).

  • PowerSchool: client ID + secret from the PowerSchool plugin admin.
  • Skyward: OneRoster credentials issued by your Skyward representative.
  • Infinite Campus: OAuth credentials configured in Campus System Administration.
  • OneRoster CSV: upload a ZIP of the standard OneRoster files (or point at an SFTP path).
Connector reference on GitHub →
5

Trigger your first sync

After saving credentials, hit Run sync. The console streams progress in real time and writes a full report to the audit log. Most first syncs take 1–10 minutes depending on district size. Subsequent syncs are scheduled per the cadence you configure under Sync → Schedule.

6

Generate an API token

Settings → API tokens lets you mint bearer tokens for downstream apps that want to read the OneRoster API. Tokens are shown once and stored hashed — copy the value into your secret manager immediately.

Availability: Full stack tier, or any self-hosted install. Connecting your SIS is included on every tier; serving that roster outward to other systems is not. See pricing →

Read the API docs →
7

Set up SAML SSO (optional)

Under Identity → SAML, Chalk can be either an IdP (issuing SAML assertions to your downstream apps) or a service provider (federating admin login to your district IdP). The SP-side setup steps — metadata URL, entity ID, attribute mapping — live in the repo README.

Availability: Full stack tier, or any self-hosted install. Connecting your SIS is included on every tier; serving that roster outward to other systems is not. See pricing →

SAML setup guide on GitHub →
8

When to contact support

If a sync fails with an opaque error, a downstream app rejects a credential, or you hit a security concern, reach out. Include the tenant slug and the audit-log timestamp so we can find your trace quickly.

Contact support →

What's next?