TypeScript SDK

@auvy-os/client is the official public SDK for AUVY. Use auvy.resources for browse, search, and catalog operations; auvy.resourceStore for assets and artifacts; auvy.receptors, auvy.neurons, auvy.pathways, and auvy.jobs for gateways and execution. See SDK resources and source of truth.

Default integration is one workspace API key: fromApiKey() bootstraps workspace id/slug from the API. Advanced options cover manual config and browser (publishable key + JWT).

Install

npm install @auvy-os/client

Authentication (API key first)

Mode	Best for	Setup
`fromApiKey()`	Servers, scripts, agents	Recommended. Pass the key string, or call with no args when `AUVY_API_KEY` is set. Same bootstrap as `createAUVYClient.fromApiKey(key)`.
`fromApiKey({ baseUrl, ... })`	Env + overrides	Merges `AUVY_API_KEY` / `AUVY_API_URL` with optional fields.
`createAUVYClient({ apiKey, ... })`	Advanced server config	Manual `baseUrl` / `workspaceSlug` without bootstrap.
`createAUVYClient({ publishableKey, getAccessToken })`	Browser apps	Publishable key plus user JWT.
`createAUVYClient.fromEnv()`	Sync env read (no bootstrap)	Does not call the API for workspace context; prefer `fromApiKey()` for API keys.

fromApiKey validates the key and calls GET /v1/session/context so workspace_id and workspace_slug are set automatically.

Server quick start

import { fromApiKey } from '@auvy-os/client'

const auvy = await fromApiKey(process.env.AUVY_API_KEY!)
// or: const auvy = await fromApiKey()

const receptors = await auvy.receptors.list()
const { receptor } = await auvy.receptors.get('my-workspace', 'support-bot')
const { job_id } = await auvy.receptors.fire(receptor.id, {
  message: 'Summarize the latest incidents',
})

Browser quick start

import { createAUVYClient } from '@auvy-os/client'
import { createClient } from '@supabase/supabase-js'

const supabase = createClient(SUPABASE_URL, SUPABASE_PUBLISHABLE_KEY)

const auvy = createAUVYClient({
  publishableKey: process.env.NEXT_PUBLIC_AUVY_PUBLISHABLE_KEY!,
  workspaceSlug: process.env.NEXT_PUBLIC_AUVY_WORKSPACE_SLUG,
  getAccessToken: async () => {
    const { data: { session } } = await supabase.auth.getSession()
    return session?.access_token ?? null
  },
})

Environment variables

The SDK supports these environment variables:

AUVY_API_KEY for backend API-key auth
AUVY_API_URL or NEXT_PUBLIC_AUVY_API_URL for self-hosted or local API URLs
AUVY_WORKSPACE_SLUG or NEXT_PUBLIC_AUVY_WORKSPACE_SLUG for default workspace scope
AUVY_PUBLISHABLE_KEY or NEXT_PUBLIC_AUVY_PUBLISHABLE_KEY for browser auth
AUVY_API_VERSION for explicit API version overrides
AUVY_TIMEOUT_MS for request timeouts

Core capabilities

resources (browse, search, trees, catalog symmetry) plus typed clients for receptors, jobs, resourceStore (assets and artifacts), traces, neurons, reflexes, skills, interventions, and public share flows
Jobs, streaming, and errors — createStream(auvy, jobId), share tokens
Built-in retry and rate-limit handling
Async pagination utilities and listAll() helpers
Interceptors — auvy.interceptors.add(...) on the client from fromApiKey() / createAUVYClient() (shared request pipeline)
Public share-token helpers for public receptor and trace flows

Packages

Package	Entry	Credential
`@auvy-os/client`	`fromApiKey()`	API key or publishable key + JWT
`@auvy-os/connect-client`	`connectFromSession()`	Publishable key + JWT (browser)
`connect-client/server`	`connectRunTool()`	Server deployment credentials

I want to…	Use
Invoke receptors / neurons from a backend	`fromApiKey()`
Embed AUVY OS in a browser app	`createAUVYClient({ publishableKey, getAccessToken })`
OAuth integration picker in your UI	`connectFromSession()` — Connect SDK

AUVY OS /v1/integrations returns 410 — integration OAuth lives on Connect, not the AUVY OS API.

Out of scope for this docs set

Credential types and API key setup: Authentication and First SDK call.

Next steps

SDK source of truth — canonical method names for agents
SDK resources — full namespace map
Jobs, streaming, and errors — invoke, stream, retry
Connect SDK — integration OAuth in browser apps
First SDK call — end-to-end onboarding
Agent harness — MCP and CLI for assistants

Are you an AI agent? Fetch agent-onboarding/SKILL.md and llms.txt before integrating.

TypeScript SDK

On this page