Skip to main content

Getting started

This guide covers how to work with Arco inside the Kosmos prototype monorepo.

Get a hosted instance​

Sign up at app.kosmos.computer to provision your own Kosmos instance at https://kosmos-<name>.fly.dev. After checkout, open your instance URL and create your owner account.

Returning customers can sign in with the email used at checkout or their instance name.

Prerequisites​

  • Node.js 22+
  • npm (workspaces enabled at repo root)

Run Kosmos + docs locally​

From the Kosmos repo root:

npm install

# Kosmos shell (port 4610) + API server
npm run dev
SurfaceURLPackage
Kosmos prototypehttp://localhost:4610Kosmos-computer/Kosmos
Kosmos marketinghttps://www.kosmos.computerKosmos-computer/www
Arco docshttps://docs.kosmos.computerKosmos-computer/docs

To work on these docs locally, clone Kosmos-computer/docs and run npm start.

Where Arco lives in the codebase​

src/styles/tokens.css     # --arco-* design tokens
src/styles/ui.css         # BEM classes for primitives
src/components/ui/        # React wrappers (Button, Input, …)
src/components/patterns/  # Layout patterns (MasterDetail, Section)
src/components/agent-blocks/  # Chat block renderers
src/apps/appview/         # Generated app surface (AppSurface)

Using tokens in new UI​

Always reference tokens — never hardcode colors or spacing:

.my-panel {
  background: var(--arco-bg-surface);
  color: var(--arco-text-primary);
  border: 1px solid var(--arco-border);
  border-radius: var(--arco-radius-m);
  padding: var(--arco-space-l);
}

Theme switching uses html[data-theme="dark"|"light"].

Using UI primitives​

import { Button, Input, EmptyState } from "@/components/ui";

export function Example() {
  return (
    <EmptyState title="No items" action={<Button variant="primary">Create</Button>}>
      <Input placeholder="Search…" />
    </EmptyState>
  );
}

Next steps​