# 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

```ts
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:

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](https://sailfork.com/docs/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](https://sailfork.com/docs/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](https://sailfork.com/docs/sdk-typescript-testing#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

```ts
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.

```ts
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](https://sailfork.com/docs/sdk-typescript-testing).
The same topic for Python: [Python client](https://sailfork.com/docs/sdk-python-client).

---

Every docs page: https://sailfork.com/llms.txt
