Sessions without a repository

The profile decides whether a repository is used. If the profile's repository_mode is required, every session sends repository_id (a session of an agent with GitHub settings, or a profile the workspace ceiling decides, may leave it out, as the section below says); if it is none, it does not; if it is optional, either works. A session created without a repository starts in an empty workspace. The SDK examples use the werft client made in Install the SDK, and the HTTP API examples use the shell variables API (the server address) and KEY (the key).

Check the profileCopy Anchor Link

const { items } = await werft.profiles.list();
for (const profile of items) console.log(profile.id, profile.repository_mode);

claude-coding-auto required
claude-coding-local required
general none

The general profile of the development server (Run the development server) is none.

Create without a repositoryCopy Anchor Link

Create the session without repository_id.

const created = await werft.sessions.create({
  profile_id: "general",
  message: 'GATE-SPEC {"id":"no-repo","steps":[],"final":"no repository here"}',
});
console.log(created.status);
const session = await werft.sessions.get(created.session_id);
console.log(session.repository_id, session.repository);

queued
null null

When it does not match the profileCopy Anchor Link

Sending repository_id to a none profile, or leaving it out of a required profile, is 422 UNSUPPORTED_CAPABILITY. The exception is a session of an agent with GitHub settings, or a profile the workspace ceiling decides: either starts without a repository even on a required profile.

import { isApiError } from "@werft-ai/sdk";

try {
  await werft.sessions.create({
    profile_id: "general",
    repository_id: "sample-app",
    message: "hello",
  });
} catch (error) {
  if (!isApiError(error)) throw error;
  console.log(error.status, error.code, error.message);
}

422 UNSUPPORTED_CAPABILITY Profile general runs without a repository: omit repository_id

With no repository there is nowhere to push. A push request for this session is 409 PUSH_SOURCE_MISSING. When you change the profile of a session in progress, you can change it only to a profile that does not use a repository (optional, none). A profile the workspace ceiling decides may also be required, and a session bound to an agent release cannot change its profile (Change the profile of a running session).

An agent session starts without a repositoryCopy Anchor Link

When you omit repository_id on a session made from an agent release, an agent with GitHub settings starts without a repository. That is the default for agent sessions, not an exception. The agent sees the allowed repositories with list_repositories and attaches only the ones the task reads or changes with attach_repository (Attaching a repository mid-session). An attached repository enters the workspace as a git remote, and writing to it goes through approval with one push request per repository.

In a session without a repository, put the files you want collected as outputs in out/ at the workspace root; a checkpoint collects the files under it. If you send repository_id, the session starts on that repository, and an older agent with no GitHub settings yet starts on its release's repository.

Next stepsCopy Anchor Link

• Send: send a message to a session