Getting Started with Gipity

The full-stack platform tuned for AI agents. Gipity is an AI agent with 90+ tools and a full cloud platform. Describe what you want - your agent builds it, deploys it, and runs it.

Installing & Accessing Gipity

Nothing to install for the normal path - Gipity is a cloud platform you use in your browser. The CLI is an optional power-user add-on.

• In the browser (the normal way): Sign up at https://gipity.ai. You get a "Home" project (a scratch workspace) and a default agent named "Gipity" automatically. Describe what you want and the agent builds, deploys, and hosts it - apps go live at dev.gipity.ai/... (testing) and app.gipity.ai/... (production). No IDE, no local runtime, nothing to set up.
• The optional CLI: Install globally with npm i -g gipity (requires Node.js), then gipity login to authenticate. Use it standalone to drive your projects from a real terminal, or launch your coding agent - Claude Code, Codex, or Grok - with the whole stack wired up in one command: npm i -g gipity && gipity build (it picks the project, agent, and model). Prefer your own flow? gipity init in any project directory wires up whichever agent you already use. Either way Gipity syncs your files, deploys, and records your sessions to the project automatically - watch them live in the web CLI (gipity init --no-capture opts out of recording).
• Web CLI on your phone: Connect this computer to gipity.ai with gipity connect so the web CLI can drive it - one command logs you in, pairs the device, starts the relay in the background, and installs the OS login service so it relaunches at boot. It does NOT launch a coding agent (use gipity build for that, or accept its first-run prompts, which run the same pairing). In the web CLI, start a chat with /relay (or /chat claude) to dispatch your messages to the coding agent on your machine. This "on your own computer" relay uses your existing Claude, Codex, or Grok subscription - the cheapest way to pay for tokens. No spare computer? Add an Anthropic API key in the web CLI (/relay offers a prompt) to run a Gipity-hosted cloud relay instead, billed per token.

For most people: sign up at https://gipity.ai and build in the browser. Reach for the CLI only to work from a local terminal or pair with a local coding agent.

Agent API tokens (headless agents & CI)

For something that runs unattended - a CI job, a cron, or a self-hosted coding agent (e.g. Hermes) in an ephemeral container - use a long-lived agent API token instead of an interactive gipity login. There's no email code to read, and it survives fresh containers because it's an env var, not a session file on disk. A token acts as your account (usage bills to you), never expires unless you set --expires, and can be revoked instantly.

• Mint one from a logged-in CLI or the web CLI: gipity token create --name "my agent". The token (gip_at_...) is shown once - copy it then; it can't be retrieved later.
• Use it: set GIPITY_TOKEN=gip_at_... in the agent's environment. The CLI picks it up automatically and skips login, so gipity add, gipity deploy dev, gipity page inspect, and the rest all just work.
• Manage: gipity token list and gipity token revoke <id>. Your active token count also appears on the Plan tab in Monitor.

Credits

Everything on Gipity runs on credits. 10,000 credits = $10 (1 credit = $0.001).

What Costs Credits

• Chat messages (LLM calls) - the primary cost, varies by model
• Code execution (sandbox runs)
• Image generation
• Text-to-speech (streaming and batch)
• Audio tools (sound effects, music, transcription, isolation)
• Web and Twitter search
• App deployment
• Cross-model queries (query_llm)
• Workflow execution (each step is an LLM call)

Checking Balance

Ask "what's my credit balance?" or "how many credits do I have?" - the agent can check via the credits tool.

Credit Types

• Subscription credits: Granted with a subscription plan. Expire 31 days after grant. Renewed each billing cycle.
• Purchased credits: Bought a la carte. Expire 90 days after purchase.
• Credits are consumed in FIFO order (soonest-expiring first).

Purchasing Credits

Ask "how do I buy credits?" or "I need more credits" - the agent can show available packages and guide the purchase flow.

Projects

Projects are isolated workspaces - like drives on a computer. Each project has its own files, databases, conversations, memory, and deployed apps.

• Home project: Auto-created on signup. Acts as your scratch pad. Cannot be deleted.
• Create a project: /project create <name> or ask the agent to create one
• Switch projects: /project <name> or /project switch <name>
• List projects: /project list or /p list

Every file belongs to a project. There is no "general" workspace.

Agents

An agent is your personal AI. New accounts start with one default agent named "Gipity."

• Create another agent: /agent create <name> - useful for different personalities or model preferences
• Switch agents: /agent <name> or /agent switch <name>
• Customize: Change model (/agent set model <id>), voice, temperature, or personality (soul)
• Soul: The agent's personality and behavioral rules. Edit with /agent soul or ask the agent to update its own soul.
• Goal & Rules playbook: An agent can carry a goal and a growing rulebook (manual rules you set + learned rules it distills from your corrections). The same brain — soul, goal, rules, learn — is reachable with parity from every channel:
  • Local CLI: gipity agent soul ["text"], gipity agent goal ["text"] [--clear], gipity agent rules [add "text" | rm <rule-guid>], gipity agent learn --original "..." --comment "...".
  • Web terminal: /agent soul, /agent goal [text|--clear], /agent rules [add|rm], /agent learn --original … --comment …, /agent set model|temp, /mem.
  • The agent itself (in chat): soul_write, agent_profile_update (now includes goal), and agent_rules (list/add/remove) tools — so Gip can curate its own brain.
  • Deployed apps: call the account-scoped control plane cross-origin (session-cookie authed) — GET/PUT /account/agents/:guid/{soul,goal}, GET/POST/DELETE /account/agents/:guid/rules, POST /account/agents/:guid/learn, GET /account/agents — so an app dashboard can show and edit its agent's brain without a server change.

File Uploads

Attach files (images, PDFs, text, code) to your chat message. The agent can read and process them.

How Uploads Work

• Original files are always preserved - processing for the AI never modifies the stored file
• Images: If larger than 5MB or 1568px on the longest side, a resized copy is created for the AI while the original stays intact
• Text/code files: If larger than 1MB, the AI sees a truncated version but the full file remains on disk
• PDFs: Sent to the AI as-is (no truncation)
• Max upload size: 100MB per file
• Supported for AI input: images (JPEG, PNG, GIF, WebP), PDFs, text/code files (50+ extensions)
• Other file types: Saved to your project files but not sent to the AI

Storage

• Quota: per-plan (call credits_products to see the current plan's storage and concurrent-chat limits)

Deploying Apps

After building a web app or game in a project:

• Dev deploy: /deploy dev - pushes to dev.gipity.ai
• Prod deploy: /deploy prod - pushes to app.gipity.ai
• Auto-deploy: Toggle in the status bar - every file write auto-deploys
• URL: https://{target}/{your-slug}/{project-slug}/

3D World

3D World is the 3D multiplayer game template on Gipity. All 3D World games share the same visual style, physics engine (Rapier), and multiplayer backend (Gipity Realtime). All files are fully editable.

Add a 3D World project with add name=3d-world (web agent) or gipity add 3d-world (CLI). This creates a playable 3D game with Three.js + Rapier physics + Gipity Realtime multiplayer. Key files: config.js (metadata), settings.js (tunable values), strings.js (display text), objects.js (entity factories), game.js (orchestrator), plus engine files (core.js, world.js, physics.js, etc.).

Genres: obby/parkour, tycoon, simulator, PvP combat, shooter, tower defense, horror, racing, RPG, social.

Features: Opt-in gameplay modules enabled via config.features. Available: rocket-launcher (projectile weapon with physics explosions). Example: features: { 'rocket-launcher': true } in config.js. Features auto-initialize during boot.

Regular game requests ("make a wordle", "build a quiz") should use the standard web template - they don't need the 3D template.

Memory

The agent automatically remembers important facts from your conversations:

• Agent memory: Personal to the agent, available across all projects
• Project memory: Shared across agents in a project, scoped to that project
• You can also ask the agent to remember or forget specific things

Common Commands

Account Info

Ask "what's my email?", "when did I sign up?", "what's my subscription?", "how much storage do I have?", "how many files/projects do I have?" - the agent can look up your profile and usage stats using get_user_info.

What the Agent Can Do

Ask it to build things, explain code, analyze data, generate images, search the web, create automations, manage files, deploy apps, and more. If unsure, just ask - the agent will tell you if something is outside its capabilities.

What the Agent Cannot Do

• Access your local computer's files (unless you upload them)
• Make network requests from the sandbox (code runs in isolation)
• Access third-party services that require your personal login credentials