Core concepts

Spikefrost has maybe a dozen load-bearing nouns. Learn them once and the rest of the documentation reads easily.

App

The unit of everything. An app owns source code, a database, storage, secrets, domains, version history, deployments, agents, and connectors. It has an id like proj-b0805906.

An app is the same thing as a project. You'll see both words — the interfaces say "app", some CLI output and file paths say "project". There is one object.

Locally, an app is a checkout: a normal folder on your machine bound to the cloud app by .spikefrost/project.json. Two people (or an agent and a person) can have checkouts of the same app at once.

Environment

One app runs in several environments — always production, plus any you name (staging, dev, test). Each environment has its own worker, its own database, its own key-value store, its own storage state. They share code, history, agents, and connectors.

An environment is created the first time you deploy to it. There is nothing to provision:

sf deploy --env staging

Do not clone an app to get a staging copy. A clone is a permanently separate app that drifts away from the original. An environment is promotable and disposable — that's the whole point. See Environments.

Commit

Spikefrost apps are under Spike VCS, a snapshot version-control system built into the platform. A commit is a full snapshot of the app's file tree with a message, an author, and parents.

The thing to internalize: AI turns and editor saves commit automatically. When an agent finishes changing your app in the cloud, that's a commit. When you work in a local checkout, you commit explicitly with sf vcs commit. Either way the history is one line you can read, diff, and roll back.

This is not git. There is no git repository in an app checkout. See Version control.

Deployment

A deployment is one attempt to make a commit live in an environment. Deploys are commit-anchored — they build exactly that snapshot's tree — and each one produces a record with a per-resource event stream: build, bundle, each database migration, the worker, secrets, agent and routine reconciliation.

Committing and deploying are separate steps unless you turn on autodeploy, which ties a branch to an environment so every commit to that branch ships. See Build and deploy.

Agent

An agent is an actor inside an app. It has:

• Instructions (sometimes called a rulebook) — what it's for, how it behaves, what it must never do
• A model — which AI model runs its turns
• Tools — an explicit allowlist of what it may call
• Channels — where it can be reached

Agents live in the app's code, which means they are versioned, reviewed, and deployed like everything else, and they reach the app's data through the app's own routes rather than by improvising SQL. An app can have several agents with different jobs, and they can hand work to each other.

Connector and channel

A connector is a doorway into your app from outside. Each one is owned by exactly one agent — the agent that answers what arrives through it. The kinds:

Connector	What arrives
Embedded chat	Messages from a chat widget on your website
Web form	Submissions from a hosted form
Webhook	HTTP POSTs from another system
Email	Mail sent to an address your app owns
Slack	Messages and mentions in a Slack workspace
Gmail / Outlook	Mail in a mailbox you connect
SMS / voice	Texts and calls

"Channel" is the general word for the medium; "connector" is the configured instance. One agent, several connectors, is normal — the same support agent answering the widget, the shared inbox, and Slack.

Job

A job is one unit of agent work: a goal, a transcript of what the agent did, tools it called, and an outcome. Jobs are the audit trail. A message in the chat widget starts a job. So does a cron routine firing, a queue message arriving, or an operator running sf jobs start --goal "...".

Jobs can nest: an agent can delegate to another agent, producing a child job, and the parent resumes when the child finishes. That tree is the record of what your app actually did.

Routine

A routine is a schedule. It fires on a cron expression and starts work — either waking an agent or calling one of your app's own HTTP endpoints. Nightly reports, hourly syncs, Monday-morning digests.

A routine causes jobs; it is not a job itself.

Skill

A skill is a written instruction set the platform hands to an agent when it's relevant — the operating knowledge for a task ("how to build a web app here", "how to configure a form", "how to publish to the App Store"). Some ship with the platform; you can also write your own and assign them to your agents. Skills are how agents stay consistent without you pasting the same instructions into every rulebook.

Tool

A tool is a capability an agent can call: provider#tool_name, like gmail#send_email or openai-image#create_image. Tools cover third-party services (through connectors your team has configured) and platform capabilities. Your app's own transactional endpoints can be published as tools too, so agents change shared data through code that enforces your rules rather than with raw SQL.

Tools are allowlisted per agent. An agent can only call what it was given.

Team

A team owns apps, connectors, credentials, and the balance that AI usage meters against. Users belong to teams with roles, and access to individual connectors can be scoped further (read / write / admin) so a contractor's agent can't reach the payments integration.

Everything you do happens in the context of one active team. sf teams lists yours; sf team use <name> switches.

How it fits together

A plausible app, in these words:

A team owns an app. The app is deployed to two environments. Its code came from a series of commits, most written by an agent during chat turns. It serves a marketing site from the edge and stores leads in its database. A support agent owns two connectors — the site's chat widget and a support inbox — and each incoming message starts a job. A routine wakes that agent every morning to email a digest of yesterday's unanswered threads. The agent is allowed exactly three tools, one of which is the app's own create_lead operation.

Next

• Getting started — do it rather than read about it.
• The desktop app — where most of this is visible as buttons.
• App anatomy — where each of these lives in the file tree.