# d1v.ai

> d1v.ai is a visible, controllable, and traceable Agent workspace for building and operating software with cloud or paired local runtimes.

## Start here

- [Agent README](https://d1v.ai/agent-readme.md): Machine-readable operating instructions, safety rules, and verified d1v CLI commands.
- [Documentation](https://d1v.ai/docs): Product and developer documentation index.
- [CLI install](https://d1v.ai/cli-install): Installation, authentication, local runtime, and troubleshooting guide.
- [CLI reference](https://d1v.ai/docs/cli): Human-readable d1v CLI documentation.
- [Full LLM context](https://d1v.ai/llms-full.txt): Expanded product and CLI context for AI systems.

## Product references

- [Core concepts](https://d1v.ai/docs/concepts): Projects, workspaces, runtimes, sessions, preview, and production.
- [Architecture](https://d1v.ai/docs/architecture): Environments, build loop, promotion, and rollback.
- [Integrations](https://d1v.ai/docs/integrations): GitHub, authentication, payments, analytics, and environment safety.
- [API](https://d1v.ai/docs/api): API keys, errors, pagination, webhooks, and retries.
- [Download app](https://d1v.ai/download): iOS, Android, macOS, and Windows clients.


---

# d1v.ai Agent README

This document is the machine-readable operating guide for AI coding agents working with d1v.ai and d1v CLI.

## Product model

- d1v.ai is an Agent workspace for defining tasks, running coding agents, inspecting execution, and reviewing results.
- A project can use a cloud runtime or a paired local runtime.
- Existing sessions remain pinned to the runtime where they started.
- The local agent opens an outbound connection to d1v.ai. Normal runtime control does not require an inbound port on the developer machine.

## Safety rules

1. Never print, log, upload, or commit API keys, auth tokens, passwords, or local `.env` files.
2. Treat preview and production as separate environments. Validate with test credentials before replacing them with production credentials.
3. Inspect the current repository and its `AGENTS.md`, `README.md`, and project plan before editing.
4. Prefer structured output with `--format json` when a command is consumed by automation.
5. Verify command exit status and resulting state. Do not infer success from terminal text alone.
6. Do not silently fall back from an unavailable local runtime to a cloud runtime.

## Install and verify

```bash
curl -fsSL https://d1v.ai/install/d1v-cli.sh | bash
d1v --version
d1v runtime doctor
```

The installer downloads a release archive from GitHub and verifies its SHA-256 checksum before installation.

Alternative installation methods:

```bash
brew install d1v-ai/tap/d1v
cargo binstall d1v-cli
cargo install --locked d1v-cli
```

## Authenticate and inspect

```bash
d1v auth login
d1v auth status
d1v project list --format json
d1v github status
```

For non-interactive automation, provide credentials through a secret manager. Supported variables include `D1V_API_KEY`, `D1V_AUTH_TOKEN`, and `D1V_BASE_URL`.

## Pair and start a local runtime

```bash
d1v runtime doctor
d1v agent pair
d1v agent start
d1v agent status
```

When the web UI supplies a pairing code:

```bash
d1v agent pair --code <pairing-code>
```

Bind an existing local directory to a project:

```bash
d1v agent project bind --project-id <project_id> --path ~/work/my-app
```

Create or import a local project directory when required:

```bash
d1v agent project create --project-id <project_id> --name my-app
d1v agent project import --path ~/work/my-app --project-id <project_id>
```

## Expose a local HTTP service

```bash
d1v expose 3000
d1v expose list
d1v expose close <binding_id>
```

The free CLI expose path is intended for temporary HTTP development traffic. Keep authentication enabled in the application and do not expose private admin or database interfaces.

## Diagnostics and maintenance

```bash
d1v runtime doctor
d1v config show
d1v upgrade
d1v uninstall
```

Useful environment variables:

- `D1V_FORMAT`: default output format, such as `json`
- `D1V_LANG`: output language
- `D1V_LOG_FILE`: diagnostic log destination
- `NO_COLOR`: disable terminal color
- `RUST_LOG`: log filtering

## Canonical references

- Install guide: https://d1v.ai/cli-install
- CLI documentation: https://d1v.ai/docs/cli
- Core concepts: https://d1v.ai/docs/concepts
- Public expose: https://d1v.ai/docs/expose
- Documentation index: https://d1v.ai/docs
- CLI source and releases: https://github.com/d1vai/d1v-cli
- OpenAPI viewer: https://d1v.ai/openapi


## Agent execution contract

When working in a d1v.ai project:

1. Read repository instructions and inspect the current state before changing files.
2. Define the requested outcome and explicit acceptance checks.
3. Keep test and production credentials separate; never commit secret files.
4. Run the smallest relevant checks while editing, then run the repository's complete required checks before reporting completion.
5. Record commands, results, and unresolved risks so work can be traced or rolled back.
6. Do not claim deployment, synchronization, or runtime success without authoritative output.