helix.config.ts reference

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 environment those IDs live in. ./helix.config.ts is the default; a project with several deploy targets keeps one config file per target and selects one with --config.

Type definition

// @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
  environment?: string;  // Helix environment, written by helix env 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:

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

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

Keys

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.

environment

The Helix environment the CLI talks to, written by helix env set <environment> and persisted for later commands. This is separate from the optional --env <environment> flag on login, logout, and whoami, which selects the environment for a single session command and doesn’t read the config file. See the configuration model.

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:

// 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 and the ctx.ai() reference.

Complete example

// 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 env set <environment> writes an environment string when you need to persist which Helix environment the CLI talks to.

What does not go in this file

TypeScript path aliases

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

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

// 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, env set, the workspace commands, and mcp) accepts --config <path>. Resolution precedence, highest first:

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:

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

// 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.