# helix.config.ts reference

> Every key helix.config.ts accepts today: name, projectId, workspaceId, region, and authentications, with types and semantics.

`helix.config.ts` declares a Helix project's identity and its authentication aliases. The CLI reads it at build time, the dev server at startup, and the SDK at runtime. A config file names one target: the project, the workspace and project IDs the CLI works against, and the region those IDs live in. `./helix.config.ts` is the default; a project with several deploy targets keeps [one config file per target](#per-target-config-files) and selects one with `--config`.

## Type definition

```typescript
// @trayai/helix-sdk

interface HelixConfig {
  name: string;          // project name, used when the first deploy provisions
  workspaceId: string;   // UUID of the Tray workspace
  projectId?: string;    // UUID of the provisioned project
  region?: string;       // Helix region, written by helix region set

  authentications?: Record<string, string>;  // alias to auth UUID
  aiProviders?: Record<string, AiService | { service: 'openai-compatible'; baseUrl: string }>;
}

type AiService = 'openai' | 'anthropic' | 'google' | 'mistral' | 'cohere' | 'openai-compatible';
```

Export the object with `defineConfig` so the compiler checks the shape:

```typescript
// helix.config.ts
import { defineConfig } from '@trayai/helix-sdk';

export default defineConfig({
  name: 'customer-health',
  workspaceId: 'f8e7d6c5-4b3a-2190-8765-abcdef012345',
});
```

## Keys

| Key | Type | Required | Purpose |
|---|---|---|---|
| `name` | `string` | Yes | The project name. `helix init` writes it, and the first `helix deploy` uses it when it provisions the project. |
| `workspaceId` | `string` (UUID) | Yes | Ties the project to a Tray workspace. Determines which authentications resolve, locally and on deploy. |
| `projectId` | `string` (UUID) | To deploy only | The provisioned project this checkout points at. Names the production subdomain and the resources a deploy provisions. |
| `region` | `string` | No | The Helix region the CLI talks to: `us1`, `eu1`, `ap1`, or `ap2`. Written by `helix region set`. |
| `authentications` | `Record<string, string>` | No | Maps human-readable aliases to auth UUIDs. Used as `ctx.http.authed('alias')`. |
| `aiProviders` | `Record<string, AiService \| object>` | No | Declares which AI SDK service backs an authentication alias, for `ctx.ai('alias')`. |

### name

The project's name. `helix init [project-name]` writes it into the scaffold. On the first `helix deploy` the platform provisions a project under this name, so it's the label you see in the dashboard's Projects list. The deploy also generates an AI description of the project, and regenerates it on every later deploy.

`helix deploy --name <name>` overrides the config value for that one deploy.

### workspaceId

Required UUID. The workspace matters both locally and on deploy: `ctx.http.authed('alias')` resolves against the workspace's auth service even during `helix dev`, and agent tooling asks the workspace which authentications are available.

Set it with `helix workspace select` (interactive picker) or `helix workspace set <id>` (when you already know the ID), or pass `helix init --workspace-id <id>` at scaffold time.

### projectId

Optional UUID until you deploy. Nothing is provisioned when you run `helix init`, so a fresh project has no ID: the first `helix deploy` provisions one, and later deploys update that project in place. Set it yourself with `helix project set <id>` to point a checkout at an existing project, or pass `helix init --project-id <id>`.

The project ID names the production subdomain, `https://{project-id}.helix-app.ai`, and the resources provisioned for the project. It's also what `helix dev` needs to reach persistent key-value storage: with no project ID, local KV is in-memory and resets when you restart the dev server.

### region

The Helix region the CLI talks to, written by `helix region set <region>` and persisted for later commands. Helix runs as four regional deployments, `us1` (the default), `eu1`, `ap1`, and `ap2`; your workspace lives in one of them, and this field points the CLI at it - it doesn't choose one for the workspace. This is separate from the optional `--region <region>` flag on `login`, `logout`, and `whoami`, which selects the region for a single session command and doesn't read the config file. See [regions](/documentation/concepts/configuration/#regions).

### authentications

Maps aliases to auth UUIDs stored in Helix. Your code references the alias (`ctx.http.authed('salesforce_prod')`); the UUID points to a credential record on Helix's servers, and all credential injection happens server-side. Credentials themselves never appear in this file, which is why the mapping is safe to commit.

Write entries with `helix auth connect` (interactive) or `helix auth add <alias> <uuid>` (when you know the UUID). Authentications are created in Tray iPaaS today, not in Helix. Calling `authed()` with an alias missing from this map throws immediately, and the error lists the aliases that are available.

### aiProviders

Declares which AI SDK service backs an authentication alias, so `ctx.ai('alias')` knows which provider package to use before any request exists:

```typescript
// helix.config.ts
export default defineConfig({
  authentications: {
    anthropicKey: '<your-anthropic-auth-uuid>',
    onPremKey: '<your-openai-compatible-auth-uuid>',
  },
  aiProviders: {
    anthropicKey: 'anthropic',
    onPremKey: { service: 'openai-compatible', baseUrl: 'https://models.internal.example.com' },
  },
});
```

The shorthand string form (`'openai'`, `'anthropic'`, `'google'`, `'mistral'`, `'cohere'`) works for the five first-party services. `openai-compatible` (self-hosted endpoints such as vLLM or Ollama) needs the object form with `baseUrl`, which must be `https:`; an `http:` value fails when the config loads rather than on the first call. An alias used with `ctx.ai()` but missing from this map throws `SdkError.aiProviderNotConfigured`, naming the exact line to add. See [calling AI models](/documentation/guides/ai/) and the [`ctx.ai()` reference](/documentation/reference/context/ai/).

## Complete example

```typescript
// helix.config.ts
import { defineConfig } from '@trayai/helix-sdk';

export default defineConfig({
  // Project name. The first deploy provisions a project under this name.
  name: 'customer-health',

  // Workspace UUID (required). Auth aliases resolve against this
  // workspace, locally and on deploy.
  workspaceId: 'f8e7d6c5-4b3a-2190-8765-abcdef012345',

  // Project UUID. Written by the first deploy, or by helix project set.
  projectId: 'a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d',

  // Alias to auth UUID. Use as ctx.http.authed('salesforce_prod').
  authentications: {
    salesforce_prod: '1a0fbf5c-2c9e-4aa1-ada3-ccbba65019ab',
    openai: 'ee41bc90-1234-5678-9abc-def012345678',
  },
});
```

`helix region set <region>` writes a `region` string when you need to persist which Helix region the CLI talks to.

## What does not go in this file

| Concern | Where it lives |
|---|---|
| Credential values and injection rules | Helix's servers, alongside the credential records. Config holds only alias-to-UUID mappings |
| Your Tray session token | `~/.tray.config`, written by `helix login` |
| Function-level settings (input schemas, handlers) | The function files, via `defineFunction` |
| Who can open the deployed app | The project's Access Control tab in the dashboard, not a code or config construct |
| Which region your workspace runs in | Set when the workspace is provisioned. The `region` field only points the CLI at it, it doesn't move the workspace |
| Infrastructure settings (runtime, memory) | The workspace, not the project |

## TypeScript path aliases

Use tsconfig path mapping so imports work from any directory depth. The canonical convention is `@project/*`:

```json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@project/*": ["./*"]
    }
  },
  "exclude": ["node_modules", ".helix"]
}
```

```typescript
// functions/api/v1/contacts/index.get.ts
import { lookupContact } from '@project/functions/_shared/contacts';
```

The SDK and CLI respect any path mapping configured in `tsconfig.json`; other conventions such as `@/lib/*` work too. Pick one and apply it consistently.

## Per-target config files

A project has one config file per deploy target, with no environment map, no merging, and no active-environment state: a different target is a different file. The target you develop against stays in `helix.config.ts`; the convention for the others is `helix.<target>.config.ts`.

```
helix.config.ts               default; the target you develop against
helix.production.config.ts
```

Every command that reads or writes project config (`dev`, `deploy`, `deployment get`, the `auth` commands, `project set`, `region set`, the `workspace` commands, and `mcp`) accepts `--config <path>`. Resolution precedence, highest first:

| Precedence | Source | Example |
|---|---|---|
| 1 | `--config <path>` flag | `helix deploy --config helix.production.config.ts` |
| 2 | `HELIX_CONFIG` environment variable | `HELIX_CONFIG=helix.production.config.ts helix deploy` |
| 3 | `./helix.config.ts` | The default when neither is set |

Commands that write config (`project set`, `auth add`, first-deploy provisioning) write to the selected file. `--config` needs CLI v0.98.0 or later.

Config files are ordinary TypeScript modules, so values shared between targets live in a module each target file imports and spreads:

```typescript
// helix.shared.ts — values common to every target
export const authentications = {
  openai: 'ee41bc90-1234-5678-9abc-def012345678',
};
```

```typescript
// helix.production.config.ts
import { defineConfig } from '@trayai/helix-sdk';
import { authentications } from './helix.shared';

export default defineConfig({
  name: 'customer-health',
  workspaceId: '9e8d7c6b-5a4f-3e2d-1c0b-9a8f7e6d5c4b',   // Acme Prod
  projectId: '1f2e3d4c-5b6a-7980-1234-567890abcdef',

  authentications: {
    ...authentications,
    salesforce: 'aa11bb22-cc33-dd44-ee55-ff6677889900',  // real Salesforce, not the sandbox
  },
});
```

Each file is complete and self-describing: reviewing a change to production means reviewing that one file, with no mental merge of a base plus overrides.

---

Canonical: https://helix.tray.ai/documentation/reference/configuration/
Any link on this page is available as markdown by appending .md to its URL.
Full corpus: https://helix.tray.ai/documentation/llms-full.txt