Skip to content

Client and sign-in (TypeScript)

Every ClientOptions field of the TypeScript SDK, how the token and host are found, a custom fetch, and how requests name the agent that sends them.

The Sailfork constructor takes one optional ClientOptions object. This page covers each field and the environment the client reads when you leave it out.

Create the client

import Sailfork from 'sailfork';

const sf = new Sailfork(); // everything from the environment

const explicit = new Sailfork({
	token: process.env.MY_SAILFORK_TOKEN,
	host: 'https://sailfork.com',
	maxRetries: 4,
	agent: 'nightly-triage',
	session: 'run-2026-11-18',
	headers: { 'x-team': 'platform' },
});

console.log(explicit.core.host); // https://sailfork.com

Every field of ClientOptions is optional.

FieldTypeDefault
tokenstringThe environment or the CLI, as described below
hoststringSAILFORK_HOST, then SAILFORK_URL, then https://sailfork.com
maxRetriesnumber2
fetchtypeof fetchThe global fetch, looked up on each call
agentstring | falseThe coding agent the environment shows, or none
sessionstringThe run id the environment shows, or none
headersRecord<string, string>none

Token

The client resolves the token on the first request and keeps it for the life of the client. It takes the first of these that is set:

  1. The token option, when it is not an empty string.
  2. SAILFORK_TOKEN, only when the client's host is the host the environment names (SAILFORK_HOST, then SAILFORK_URL, then https://sailfork.com). A client built for another host never sends that token.
  3. The token the CLI stored, read by running sailfork auth token --host <host> with a 5 second limit. This works only where the runtime exposes process.getBuiltinModule (Bun, Node 20.16 or later, Node 22.3 or later) and the sailfork command is installed.

With none of them the client sends no Authorization header. Reads on public repositories still work; everything else is a 401, an AuthenticationError. Create a token with the scopes your code needs on Access tokens.

Host

host is a site origin. The client trims it, drops trailing slashes and any path, and adds https:// when there is no scheme (http:// for a value that starts with localhost or 127.0.0.1). Anything that is not an http or https origin throws a TypeError from the constructor. A bad SAILFORK_HOST is ignored and the next source is used instead.

Agent and session

Every request names the coding agent that drives it in X-Sailfork-Agent, which is how agent permissions tell an agent from a person. The client works the name out from the environment: SAILFORK_AGENT first (none, false, 0, off, no and null mean no agent), then the markers coding agents set, such as CLAUDECODE for claude-code or CODEX_THREAD_ID for codex, then AI_AGENT and AGENT. detectAgent() returns what the environment shows.

Pass agent to name your own program, or agent: false to send none. A string is sent as given.

session becomes X-Sailfork-Session and is sent only when an agent name is set. It defaults to SAILFORK_SESSION, then the session id variable of the detected agent. detectSession() returns it.

Headers and fetch

Each request carries accept, sailfork-version, user-agent (sailfork-ts/0.1.0), the two agent headers when they apply, and then your headers, with names lower-cased. Your headers win over the defaults. RequestOptions.headers on a single call wins over both.

fetch replaces the transport. It is called with the full URL string and an init object whose headers is a plain object with lower-case names, and it must return a Response. See Test your code.

Environment variables

VariableUsed for
SAILFORK_TOKENThe token, for the host the environment names
SAILFORK_HOST, then SAILFORK_URLThe host
SAILFORK_AGENTThe agent name sent as X-Sailfork-Agent; none sends no agent
SAILFORK_SESSIONThe run id sent as X-Sailfork-Session
AI_AGENT, AGENTAgent name fallbacks, after the markers coding agents set

Inspect what the client picked

import Sailfork, { API_VERSION, VERSION, detectAgent, detectSession } from 'sailfork';

const sf = new Sailfork();

console.log(sf.core.host); // the resolved origin
console.log(API_VERSION, VERSION); // 2026-12-01 and the package version
console.log(detectAgent() ?? 'no agent named', detectSession() ?? 'no session');

Wrap fetch

fetch is called once per attempt, so a wrapper sees retries too.

import Sailfork from 'sailfork';

const logged: typeof fetch = async (input, init) => {
	const started = Date.now();
	const response = await fetch(input, init);
	console.log(init?.method, String(input), response.status, `${Date.now() - started} ms`);
	return response;
};

const sf = new Sailfork({ fetch: logged });
await sf.repo('acme/api').pulls.list({ limit: 1 });

To send requests through a proxy or a different HTTP stack, return a Response from your own function. To stub the server in tests, see Testing and runtimes. The same topic for Python: Python client.

Loading Sailfork