# Get started with Host Little

Host Little hosts GitHub applications and managed PostgreSQL. This guide is for
coding agents helping an owner deploy or operate a project.

Canonical guide: https://hostlittle.com/get-started.md
Human setup and API key settings: https://hostlittle.com/agents
Portal: https://hostlittle.com/portal

## Start here

1. Ask whether the owner wants to deploy a repository or manage an existing project.
2. If needed, have the owner sign in and create an API key at
   https://hostlittle.com/portal/settings/agents. Keep `HOSTLITTLE_AGENT_KEY` in
   the client's private environment or secret store, never in this chat, Git,
   hosted application variables, build inputs, or public `NEXT_PUBLIC_*` values.
3. Read `GET https://hostlittle.com/api/v1/account`, then
   `GET https://hostlittle.com/api/v1/projects`, with
   `Authorization: Bearer $HOSTLITTLE_AGENT_KEY`. Choose the exact project ID;
   do not guess from a similar name or assume cross-workspace access.
   For an MCP-only client, discover tools and begin with `projects_list`; do not
   invent an account tool. The API enforces permissions on every request.
4. Read the project's current deployment and configuration before changing it.
   If the client has no terminal/API tools, guide the owner through the portal
   or a connected coding client; reading this document alone does not grant access.

## Choose a tool

### MCP: local stdio server

Requires Node.js 22 or later and an MCP client that can launch a local process:

```sh
npx --yes https://hostlittle.com/downloads/hostlittle-cli-0.3.0.tgz mcp
```

Configure `HOSTLITTLE_AGENT_KEY` privately in that client's environment. Discover
its tools with `tools/list`. Tools cover project inventory, deployment activity,
standalone and attached PostgreSQL lifecycle, redacted environment reads,
permitted environment updates and redeploy requests, and feature flags.

This is a local stdio server, not a hosted remote MCP URL. ChatGPT/Claude client
capabilities differ; do not invent an HTTP MCP endpoint or imply a vendor partnership.
MCP does not return secret values.

### CLI: local development

```sh
npm install -g https://hostlittle.com/downloads/hostlittle-cli-0.3.0.tgz
hostlittle mcp
hostlittle run --project PROJECT_ID -- npm run dev
hostlittle env pull --project PROJECT_ID --output .env.local
hostlittle db list --account ACCOUNT_ID
```

Use an actual ID from project inventory. Local environment export requires
`env:local` for that project or Full owner access. `run` injects values into the
child process; `env pull` adds missing values to an ignored, untracked, private
file and preserves existing assignments. Add `.env.local` to `.gitignore` first.
Exports stop on unavailable values unless the owner explicitly requests a partial
export. Avoid printing secrets through application debug logs.

### HTTP API

Base URL: `https://hostlittle.com/api/v1`. Use the same private bearer key.

| Job | Supported route |
| --- | --- |
| Check identity and access | `GET /account` |
| Find owned/authorized projects | `GET /projects` |
| Read deployment activity | `GET /projects/:id/deploys` |
| Read redacted logs | `GET /projects/:id/logs` |
| Read attached database metadata | `GET /projects/:id/databases` |
| List or create standalone PostgreSQL | `GET /databases`, `POST /databases` |
| Read or delete PostgreSQL | `GET /databases/:id`, `DELETE /databases/:id` |
| Suspend, resume, or rotate credentials | `POST /databases/:id/lifecycle` |
| Poll durable database work | `GET /database-operations/:operationId` |
| Save a connection through local tooling | `POST /databases/:id/connection/local` |
| Read or update environment variables | `GET /projects/:id/env`, `POST /projects/:id/env` |
| Request redeployment | `POST /projects/:id/redeploy` |
| Read feature availability | `GET /projects/:id/feature-flags` |

Detailed setup: https://hostlittle.com/agents
For environment updates, send `{ "environment": "production", "key": "NAME",
"value": "VALUE", "isSecret": true }`. For redeploys, send
`{ "environment": "production" }`. Supported environments are `production` and
`development`. Start with reads and use the key's granted permissions. Do not
guess additional routes or commands.

## Permissions and configuration

Project-scoped write keys can return `pending_approval` with an approval URL.
Respect that result; do not retry to bypass approval. An enabled autonomous window
or Full owner access permits supported actions within the key's actual scope.
Full owner access covers currently owned workspaces, not the entire platform.

Ordinary environment reads remain redacted. Managed `DATABASE_URL` and
`POSTGRES_URL` aliases are controlled by the database binding, not ordinary env
writes. The authorized CLI local-export path can supply attached database values
for local development. Do not replace or reveal them through normal MCP reads.
Local env edits do not change a deployed app. Build-time/public changes require a
new build; runtime changes need the supported deployment flow.

## Deploy an app or start from a template

Use https://hostlittle.com/get-started to connect a GitHub repository and choose
its production branch. Push application changes to that connected branch.
Follow the deployment to terminal success, verify the deployed revision, and
check the real application; a queued request or successful build alone is not a
successful deployment. Inspect the existing operation before retrying.

Next.js + Postgres starter:
https://github.com/Jamyye/hostlittle-nextjs-postgres-starter

Its demo note is public synthetic data, not an authenticated notes product.
Add authentication/authorization before using customer data. Preserve existing
migrations and data; builds must not require production database credentials.

## Database and domain operations

The API, CLI, and local MCP server support standalone database create/list/get,
operation polling, suspend/resume, credential rotation, backup-first deletion,
and private local connection saving. Database writes require an owner-issued key,
the `databases:write` scope, an active autonomous window, and a caller-retained
idempotency key. Connections require `databases:connect` and are written to an
ignored local file; MCP never returns the URI in tool content. Persistent compute
resize, SQL execution, manual backup/restore management, and domain management
remain portal/provider work until their public contracts are implemented. Do not
invent those tools.

Report the project, action, revision/deployment result and any remaining step.
Never report a requested change as completed before its result is verified.