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.
| Field | Type | Default |
|---|---|---|
token | string | The environment or the CLI, as described below |
host | string | SAILFORK_HOST, then SAILFORK_URL, then https://sailfork.com |
maxRetries | number | 2 |
fetch | typeof fetch | The global fetch, looked up on each call |
agent | string | false | The coding agent the environment shows, or none |
session | string | The run id the environment shows, or none |
headers | Record<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:
- The
tokenoption, when it is not an empty string. SAILFORK_TOKEN, only when the client's host is the host the environment names (SAILFORK_HOST, thenSAILFORK_URL, thenhttps://sailfork.com). A client built for another host never sends that token.- The token the CLI stored, read by running
sailfork auth token --host <host>with a 5 second limit. This works only where the runtime exposesprocess.getBuiltinModule(Bun, Node 20.16 or later, Node 22.3 or later) and thesailforkcommand 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
| Variable | Used for |
|---|---|
SAILFORK_TOKEN | The token, for the host the environment names |
SAILFORK_HOST, then SAILFORK_URL | The host |
SAILFORK_AGENT | The agent name sent as X-Sailfork-Agent; none sends no agent |
SAILFORK_SESSION | The run id sent as X-Sailfork-Session |
AI_AGENT, AGENT | Agent 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.