# Getting Started with Gipity

The full-stack platform tuned for AI agents. Gipity is the cloud backend your coding agent builds on: hosting, databases, serverless functions, file storage, sandboxed code, GPU jobs, hosted models, media services, workflows and realtime, all driven through the `gipity` CLI.

## Install and sign in
- **Install:** `npm i -g gipity` (requires Node.js), then `gipity login`.
- **Start building:** `npm i -g gipity && gipity build` picks a project and launches your coding agent (Claude Code, Codex, Grok or opencode) with Gipity wired in. Already in your own flow? `gipity init` in any project directory wires up whichever agent you use.
- **Files sync automatically:** edit files locally; the editor hooks `gipity init` installs push every save, and `gipity sync` fixes drift.
- **Session recording is off by default.** `gipity init --capture` records this project's coding-agent sessions so you can read them later in Monitor's Chats tab.

### Agent API tokens (headless agents & CI)
For something that runs unattended - a CI job, a cron, or a self-hosted coding agent 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:** `gipity token create --name "my agent"`. The token (`gip_at_...`) is shown once; copy it then.
- **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 just work.
- **Manage:** `gipity token list` and `gipity token revoke <id>`. Monitor's Account tab lists, creates and revokes them too.

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

### What costs credits
- Sandbox runs (`gipity sandbox run`)
- Hosted model calls (`gipity ask`, app LLM calls, workflow `llm` steps)
- Image, video, speech, sound and music generation
- Transcription and web search
- GPU and CPU jobs
- Storage and databases (metered daily)

### Balance and buying
- `gipity credits` (alias `gipity plan`) shows your plan, balance and limits; `gipity credits list` compares plans and packs.
- `gipity credits buy` opens Stripe Checkout; `gipity credits manage` opens the billing portal (cancel, renew, card, invoices). Monitor's Plan tab does the same.

### Credit types
- **Subscription credits:** granted with a plan, expire 31 days after grant, renewed each billing cycle.
- **Purchased credits:** bought a la carte, expire 90 days after purchase.
- Credits are consumed soonest-expiring first.

## Projects
A project is one app: its files, databases, functions, workflows, memory and deploys. Your local directory is linked to one by `.gipity.json`.

- `gipity init [name]` creates or links a project in the current directory.
- `gipity project` lists them; `gipity status` shows the linked one.
- `gipity add <template|app|kit>` installs a template or app into an empty project, or a kit into an existing app.

## Deploying
- `gipity deploy dev` deploys to `https://dev.gipity.ai/{account}/{project}/`; `gipity deploy prod` to `https://app.gipity.ai/{account}/{project}/`.
- Apps with a `gipity.yaml` deploy in phases: files, database, functions, jobs, workflows. Unchanged phases are skipped.
- `gipity page inspect <url>` loads the deployed page in a real browser and reports errors.

## Project memory
Each project keeps notes by topic, read and written by workflow `llm` steps with the `memory` tool and by you with `gipity memory list|read|write|delete`.

## Monitor
Monitor is the Gipity web app: every project with its URLs and deploy state, traffic, errors, compute runs with their output and logs, test runs, a file browser with version restore, spend, billing, alerts, secrets and API tokens. Everything it shows goes through the same API the CLI uses.

## Common commands
| Command | What it does |
|---------|-------------|
| `gipity status` | Who you are and which project this directory is |
| `gipity add <name>` | Install a template, app or kit |
| `gipity deploy dev` | Deploy to dev |
| `gipity page inspect <url>` | Check a deployed page in a real browser |
| `gipity test` | Run the project's tests |
| `gipity db query "<sql>"` | Query the project database |
| `gipity fn logs <name>` | A function's recent logs |
| `gipity sandbox run "<cmd>"` | Run code with ffmpeg, pandas, LibreOffice and more |
| `gipity ask "<question>"` | One quick model call |
| `gipity skill list` | The docs for everything above |
| `gipity storage usage` | What is using your storage |