Phantasy

Phantasy lets you build an AI companion/VTuber who can run her own APIs, CMS, content, workflows, and business.

Think WordPress for AI companions: an installable source-available agent framework/CMS for characterized AI companions and companion-native products.

Build one character who can chat, publish, remember, automate, and run the CMS, APIs, workflows, and business around that character from the same runtime architecture. The terminal, admin shell, headless content APIs, and workflow system are operator surfaces around that character.

Core thesis: AI companions are an operating-system problem, not only an agent-framework problem.

Bundled Rally PNGTuber demos — talking, blink, idle. Default avatar path needs no Cubism SDK.

Where It Fits

Start here: one companion runtime, five workspaces, admin shell, and extensions. That is the whole flagship story for most teams.

Optional layers around that runtime (not required for first success):

• Alkahest: shared trust-rail layer below Phantasy (hosted inference, attestation, payment rails)
• Party: multi-runtime agent coordination when you outgrow one deployment
• Combo: sibling software quest network (separate repo) — not a second Party

Phantasy is not a generic agent protocol, not a trustless verification layer by itself, and not the default multi-agent control plane. Vocabulary freeze: docs/party-vs-combo.md.

Product Boundary

Phantasy owns the one-runtime character operating system:

• one companion runtime
• native bounded subagents for local fanout under that runtime
• the five workspaces: Character, Site, Business, Workflows, and Operations
• the admin shell, CLI, workflow system, and operating surfaces around one deployment
• household / multi-tenant MAID path as an opt-in packaging surface (PHANTASY_INSTALL_PROFILE=household or PHANTASY_ENABLE_HOUSEHOLD=1)

Phantasy is not the shared trust-rail layer, it is not the multi-runtime control plane, and it is not the consumer product itself.

• shared hosted inference, provider routing, attestation, and shared payment rails can live below it in Alkahest
• product-specific affection, inventory, date mechanics, and launch gating can live above it in Rally until they prove reusable
• Party is the adjacent many-runtime control plane, not the default Phantasy story

Show It In This Order

When you demo or explain the flagship product, keep usefulness ahead of economics:

1. the public-facing companion
2. the site or published content surface
3. memory or continuity inside the same runtime
4. an approval-gated workflow or operator loop
5. a business or integration action

Fastest Path

Requirements:

• Node.js 22.12+
• Bun (for the from-source path)

The only consumer npm package for GA is @phantasy/agent (@phantasy/[email protected] on Forgejo npm — not public npmjs). @phantasy/agent-core and other monorepo workspace packages are not independently published for GA. GitHub phantasy-bot/companion is a mirror only.

From source

Clone from Forgejo and boot locally:

git clone https://forgejo.thomasjvu.com/phantasy/agent.git
cd agent
bun install
./start.sh

Install from Forgejo npm (canonical package path)

Configure the Forgejo registry + token, then pin 1.0.0: docs/install-forgejo.md.

# .npmrc: @phantasy:registry=https://forgejo.thomasjvu.com/api/packages/phantasy/npm/
#         //forgejo.thomasjvu.com/api/packages/phantasy/npm/:_authToken=${FORGEJO_TOKEN}
export FORGEJO_TOKEN=…
npm install @phantasy/[email protected]

Runtime image (arm64): docker pull forgejo.thomasjvu.com/phantasy/agent:1.0.0 (amd64 deferred — see install-forgejo.md).

Install (Prime-style terminal screen)

From a checkout, or after copying install.sh:

sh install.sh

The installer probes npm view @phantasy/agent (needs Forgejo .npmrc / token for GA), then falls back to the Forgejo git URL if unpublished. It checks Node/npm, confirms, runs a global install with a full-screen status UI (plain mode: PHANTASY_INSTALLER_PLAIN=1), then prints localhost next steps. Update later with phantasy update.

Zero-install alternative (no global CLI), with Forgejo registry configured:

npx -y @phantasy/[email protected] init my-brand --yes
npx -y @phantasy/[email protected] run --config config/agents/my-brand.json

Next (localhost)

phantasy init my-brand --yes
phantasy run --config config/agents/my-brand.json
# open https://phantasy.localhost/admin
phantasy login provider --provider openai --api-key <key>

Then chat with your companion. Rotate the bootstrap admin password and auth secrets before any non-loopback host.

• admin shell: https://phantasy.localhost/admin (Portless; loopback http://127.0.0.1:2000/admin still works)
• API/server: https://phantasy.localhost or http://127.0.0.1:2000

Default path: install → init → run → provider login → admin chat.

That install is the service + admin + operator CLI in one package (@phantasy/agent). Full-screen terminal UI needs optional OpenTUI natives; without them, plain chat and the admin shell still work. Worker / embed paths can drop admin and optionals — see docs/PACKAGING.md.

Install profiles (keep it light)

Default install is a companion with PNGTuber only and the companion package surface set (core + character + admin). Household/MAID, Party, chat channels, Live2D vendor SDKs, and coding natives stay off until you opt in.

CLI profile	Flag	Avatar default	Notes
companion	(default)	PNGTuber only	Flagship path
worker	--profile worker	none enabled	Headless / VPS orchestrator
avatar-full	--profile avatar-full	pngtuber + live2d + vrm	Opt into Live2D / VRM

Package profile	Surfaces (short)	Env
companion	core, character, admin	default
household	+ household, billing (MAID extension)	PHANTASY_INSTALL_PROFILE=household
lite	core, character	PHANTASY_INSTALL_PROFILE=lite
full	+ channels + edge (PQ / heavy extras)	PHANTASY_INSTALL_PROFILE=full

# Companion (default)
phantasy init my-brand --avatar pngtuber

# Headless worker
phantasy init orchestrator --project-manager --profile worker

# Live2D opt-in
phantasy init stream --vtuber --avatar live2d,pngtuber
PHANTASY_ENABLE_LIVE2D=1 bun run setup:live2d

# Skip optional natives
npm i @phantasy/agent --omit=optional
# Docker headless: BUILD_ADMIN_UI=false

Full matrices:

• docs/install-profiles.md — CLI + package surfaces
• docs/supported-surfaces.md — supported vs experimental
• docs/lightweight-install.md — worker dist / VPS
• docs/PACKAGING.md — modularity spine

Character generation

Phantasy turns a prompt or illustration into an animated companion avatar, then binds it to the runtime (voice, chat, site, workflows).

Path	What you get
PNGTuber (default)	Identity-locked frame pack: idle, happy, blink, multi-step talking
See-through (optional)	Semantic layered PSD via see-through (SEE_THROUGH_ROOT)
Avatar 2.5D	Playable canvas layered puppet (parallax, blink, mouth, hair) — no .moc3
Live2D scaffold	Textures + JSON only — not a playable .moc3; import real Cubism packs for Live2D runtime
Live2D / VRM import	Production models you already own

Related open tools (we integrate patterns; they are specialists, not competitors for the full companion OS):

• Layer decomp: see-through
• Blink / lip materials: PachiPakuGen
• Browser 2.5D auto-rig: Anime2.5DRig

Docs + demo GIF regen:

• Character Generation
• python3 scripts/demo-media/render_pngtuber_previews.py --also-webm
• python3 scripts/demo-media/render_pipeline_and_lipsync.py (pipeline sheet + lipsync MP4)
• See-through vendor: ./start.sh ensures vendor/see-through (+ venv). Manual: bun run setup:see-through · skip: PHANTASY_SKIP_SEE_THROUGH_SETUP=1

The Site workspace is a headless CMS. Phantasy stores, reviews, publishes, and serves content APIs; your public site or app can be any frontend stack that reads /api/content/*. This repo also includes a non-shipped reference Astro frontend under apps/site/ for local dogfooding (bun run dev:site). External starters live in templates/site-frontend-starter/ and phantasy-bot/examples; Phantasy does not ship installable themes or a WordPress-style frontend package.

Forkable example apps live outside this release repo in phantasy-bot/examples, including Next.js, Astro/SvelteKit, and companion-product apps such as the Rally-style integration surface we dogfood against the same content APIs.

Optional terminal chat:

npx -y @phantasy/agent chat --config config/agents/my-brand.json

Health check:

npx -y @phantasy/agent doctor --config config/agents/my-brand.json

Doctor verifies the runtime config, local environment, product workspace briefs, 2D/3D avatar asset readiness, and live health endpoint. Coding-agent readiness checks apply under the developer shape. If local scaffold files are missing, run:

npx -y @phantasy/agent doctor --config config/agents/my-brand.json --repair-scaffold

phantasy init creates the flagship runtime config and a Convex quickstart .env in the current workspace. Run ./scripts/convex-bootstrap.sh once to start self-hosted Convex and obtain an admin key. First local login uses the bootstrap admin account on localhost. On first startup, rotate that password and generate real auth secrets before widening access.

Quickstart safety contract:

• bootstrap auth is only for loopback-only localhost use
• rotate the bootstrap admin password and auth secrets in onboarding immediately
• do not switch to non-loopback hosts, shared origins, or public exposure until rotation is complete

Deploy

Phantasy supports local-first setup and hosted deployment as separate paths.

Path	Link	Status
Docker Compose	Deploy guide	supported self-host path
Railway	Railway guide	template + deploy button; rotate bootstrap secrets; not CI live-validated
Hetzner VPS	Hetzner guide	server-owned Docker Compose path
Phala TEE	Phala TEE guide	TDX attestation validation path
Phantasy Cloud	Phantasy Cloud	proprietary control plane in phantasy-bot/cloud

Local init uses self-hosted Convex by default (./scripts/convex-bootstrap.sh). Shared and production deployments should set CONVEX_SELF_HOSTED_URL and CONVEX_SELF_HOSTED_ADMIN_KEY (or Convex Cloud CONVEX_URL + CONVEX_DEPLOY_KEY).

Add Party When You Need More Than One Runtime

Keep first success simple: get one Phantasy runtime working before adding a control plane.

Add Party when you need a Paperclip-style operator layer for:

• multiple runtimes such as Phantasy, OpenClaw, Hermes, or AGENTS.md workspaces
• quests, blocker dependencies, runs, traces, approvals, budgets, and schedules
• execution workspace readiness and source-control handoff visibility
• operator review across a party, formation, campaign, or launch effort

If OpenClaw or Hermes are useful runtime/framework references and Paperclip is the operator-company control-plane reference, Phantasy plus Party is the companion-native version of that stack: one strong runtime first, multi-runtime orchestration when needed.

Party app checkout:

The apps/party/ control plane is an optional Git submodule. A normal clone does not download or initialize it, so the default companion install stays focused on one runtime. Phantasy still ships the SDK, adapters, contract tests, and dogfood scripts under packages/party-* and scripts/party/.

Choose the Party command center explicitly when you need it:

git submodule update --init --recursive apps/party

If you cloned the repository with --recurse-submodules, this step has already been done.

Shortest Party path (after apps/party is available locally). Party is pnpm-native; the Phantasy monorepo root is Bun-native:

pnpm --dir apps/party install
pnpm --dir apps/party dev
# from monorepo root (Bun scripts / quality gate):
bun run quality:party
npm run party:onboard -- --agent companion

Then create one Party, one Agent, one Quest, send one heartbeat, and inspect the result in Activity.

What You Get

• one character runtime that resolves identity, logic, assets, and interactions across chat, scenes, site, and external shells
• versioned external APIs for character runtime metadata and integration chat
• a self-hosted operating system for AI companion businesses
• five workspaces: Character, Site, Business, Workflows, and Operations
• project-local workspace briefs: PRODUCT.md, character/CHARACTER.md, character/APPEARANCE.md, site/, business/, workflows/, and operations/ (instance paths, not monorepo apps)
• markdown-first local development with Convex system storage and optional vector-backed memory
• headless content publishing APIs with workflows, approvals, memory, and extensions
• optional in-repo reference site at apps/site (bun run dev:site); production frontends stay external (examples repo / starters), not installable themes

Pick A Shape

The launch-front-door shape is companion. VTuber, NPC, and CMS paths are more specific presets or aliases layered around the same runtime family.

• companion: the generalized default runtime for companions and embodied AI characters
• vtuber: creator-specific runtime for VTubers, PNGTubers, and stream-native characters
• npc or character: the same companion runtime, named for NPC and embodied character creation
• cms: the same companion runtime, named for WordPress-style Site workspace work
• operator: workflows, approvals, and operational execution around the same companion
• developer or coder: local repo search, git review, tracked shell tasks, headless task/file APIs; exec pi/codex via phantasy chat --harness

Examples:

npx -y @phantasy/agent init my-brand
npx -y @phantasy/agent init stream-studio --vtuber
npx -y @phantasy/agent init quest-giver --npc
npx -y @phantasy/agent init creator-site --cms
npx -y @phantasy/agent init ops-lead --operator
npx -y @phantasy/agent init repo-agent --coder

Use init for the full local quickstart env. Use create when you only need a runtime config plus the non-overwriting local workspace scaffold:

npx -y @phantasy/agent create companion my-brand
npx -y @phantasy/agent create agent --preset vtuber stream-studio
npx -y @phantasy/agent create npc quest-giver
npx -y @phantasy/agent create cms creator-site
npx -y @phantasy/agent create coder repo-agent

If the CLI is already on your PATH, you can drop the npx -y @phantasy/agent prefix and run phantasy ... directly.

Advanced Runtime Surfaces

For most teams, the answer is still @phantasy/agent (the only package required for the 0.1.x beta install path). If you are following the flagship product path, you can stop at the quickstart, workspaces, and trust model sections.

In-repo package surfaces for narrower trust boundaries exist as monorepo workspace packages. Independent npm install @phantasy/agent-core (etc.) is not the documented public path until docs/PACKAGING.md marks them published:

• flagship self-hosted OS: @phantasy/agent (use this)
• embedded runtime / providers / CLI / TUI / server-admin: monorepo packages
• optional Party collaboration for cross-agent work later (submodule / edge)

Repo development:

bun install
./start.sh
phantasy gateway status

See env matrix for the full boot-path, env-file, and Convex matrix.

Gateway execution targets now include local, docker, singularity, modal, daytona, and ssh. In this repo, modal and daytona are wired through the runtime and covered by unit tests and typecheck, but they are not part of the default live smoke loop unless you bring your own CLI credentials, mounted workspace, and remote sandbox.

./start.sh boots the Convex + markdown quickstart path by default. Use ./start.sh convex on first run (or after ./start.sh stop) to start self-hosted Convex via Docker and print the admin key. Convex data lives in the convex_data Docker volume; the dashboard is at http://127.0.0.1:6791.

Root env files now have one canonical tracked reference: .env.example. Run bun run setup:env to create or repair the gitignored .env used by ./start.sh and bun dev.

Local development still binds the agent at http://127.0.0.1:2000. ./start.sh registers a Portless alias so you can open https://phantasy.localhost/admin instead of remembering the port. First run may prompt for sudo (bind :443 + trust the local CA). Loopback http://127.0.0.1:2000/admin remains valid. PHANTASY_PORTLESS=0 skips the named URL. Port 5173 is an internal Vite HMR process only (proxied through :2000/admin); do not open :5173 in the browser.

Reset local state:

./start.sh reset-fresh       # wipe Convex data + .phantasy/, fresh admin/phantasy login
./start.sh reset-workspace   # remove .phantasy/ only; keeps Convex database

./start.sh restart only stops and re-bootstraps Convex — it does not wipe stored data or credentials.

Workspaces

• Character: identity, character logic, asset bindings, voice, memory, knowledge, and interaction orchestration
• Site: pages, posts, media, content APIs, publishing
• Business: channels, integrations, subscriptions, monetization
• Workflows: workflows, jobs, schedules, approvals
• Operations: providers, auth, logs, monitoring, developer tools

Trust Model

• Admin routes are protected by default.
• Developer, Test, and headless developer-tool file/task APIs are operator-only surfaces, not end-user product tabs.
• Internal compatibility routes may still use workbench; that name refers to Operations developer tooling, not a Workbench UI workspace.
• Authenticated admin users should be treated as operator-level host access when developer-tools is enabled.
• Shared/public developer-tools exposure requires a second explicit override via PHANTASY_ALLOW_SHARED_DEVELOPER_TOOLS=true.
• Runtime capabilities are explicit.
• External plugin loading is disabled by default.
• Remote plugin install is disabled by default.
• Published package contents are allowlisted.

Release Checks

npm run release:check

Docs And Guides

• Quickstart: apps/docs/src/docs/content/getting-started/quickstart.md
• Docs home: apps/docs/src/docs/content/index.md
• Why Phantasy: apps/docs/src/docs/content/getting-started/why-phantasy.md
• Character Logic: apps/docs/src/docs/content/features/character-logic.md
• Character Runtime API: apps/docs/src/docs/content/api/character-runtime.md
• Runtime map: apps/docs/src/docs/content/architecture/runtime-map.md
• Agent framework beta guide: apps/docs/src/docs/content/guides/advanced/agent-framework-beta.md
• Architecture overview: apps/docs/src/docs/content/architecture.md
• Runtime boundaries: apps/docs/src/docs/content/architecture/runtime-boundaries.md
• Proof ladder: apps/docs/src/docs/content/architecture/proof-ladder.md
• Replay-eval guide: apps/docs/src/docs/content/development/replay-eval.md
• Docs app: apps/docs/README.md
• Installation: apps/docs/src/docs/content/getting-started/installation.md
• Phantasy vs Party: apps/docs/src/docs/content/architecture/phantasy-vs-party.md
• Party compatibility: apps/docs/src/docs/content/integrations/party-compatibility.md
• Monorepo layout: apps/docs/src/docs/content/architecture/monorepo-layout.md
• Release checklist: apps/docs/src/docs/content/development/release-checklist.md
• Release notes and migration notes: apps/docs/src/docs/content/maintenance/open-source-release-notes.md
• 10-minute companion launch: apps/docs/src/docs/content/guides/quickstarts/companion-launch.md
• Starter asset packs: apps/docs/src/docs/content/guides/media/starter-asset-packs.md
• Contributor docs workflow: apps/docs/src/docs/content/development/documentation.md
• Contributing
• Open Source FAQ
• Third-Party Notices
• Repo layout (vendor/, third_party/, tests/, templates/, scripts/)

Community

Issues, discussions, and pull requests are welcome. For larger changes, open a draft PR or discussion early so the owning workspace and architecture shape are clear before implementation spreads.

Please follow the Code of Conduct. Security reports go to [email protected], not public issues.

License

Dual license. Core runtime and product surfaces are source-available FSL-1.1-Apache-2.0 (not OSI “open source” until the FSL change date); templates and SDK packages use MIT. See LICENSES/README.md.

Phantasy Cloud is proprietary and lives in phantasy-bot/cloud.