> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neptune.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Configure your Neptune deployments with neptune.json

The `neptune.json` file defines your project's deployment configuration, resources, and runtime settings. Your AI assistant creates and manages this file automatically - you typically don't need to edit it directly.

## Basic Structure

```json neptune.json theme={"dark"}
{
  "kind": "Service",
  "name": "my-app",
  "port_mappings": [
    { "container_port": 3000, "host_port": 8080 }
  ],
  "resources": []
}
```

## Configuration Reference

### Required Fields

| Field | Type | Description |
| - | - | - |
| `kind` | string | Must be `"Service"` |
| `name` | string | Unique project name (lowercase, hyphens allowed) |

### Optional Fields

| Field | Type | Default | Description |
| - | - | - | - |
| `port_mappings` | array | `[{container_port: 8080, host_port: 8080}]` | Port mappings for your container |
| `resources` | array | `[]` | Storage buckets, secrets, and databases |

## Port Mappings

Map your container's port to the external port:

```json theme={"dark"}
{
  "port_mappings": [
    { "container_port": 3000, "host_port": 8080 }
  ]
}
```

* `container_port`: The port your app listens on inside the container
* `host_port`: The external port (Neptune routes traffic here)
* `protocol`: Optional, defaults to `"tcp"`

> [!TIP]
>
> If your app listens on port 8080, you don't need to specify port mappings - that's the default.

## CPU and Memory

> [!WARNING]
>
> CPU and memory configuration is not available in the initial release. All deployments currently run with **256 CPU units (0.25 vCPU)** and **512 MB memory**. Configurable resources are coming soon.

## Resources

Define the cloud resources your app needs:

```json theme={"dark"}
{
  "resources": [
    {
      "kind": "StorageBucket",
      "name": "uploads"
    },
    {
      "kind": "Secret",
      "name": "API_KEY"
    },
    {
      "kind": "Database",
      "name": "mydata"
    }
  ]
}
```

> [card] [Storage Buckets](https://docs.neptune.dev/resources/storage.md)

> [card] [Secrets](https://docs.neptune.dev/resources/secrets.md)

> [card] [Databases](https://docs.neptune.dev/resources/databases.md)

## Complete Example

```json neptune.json theme={"dark"}
{
  "kind": "Service",
  "name": "my-saas-app",
  "port_mappings": [
    { "container_port": 3000, "host_port": 8080 }
  ],
  "resources": [
    {
      "kind": "StorageBucket",
      "name": "user-uploads"
    },
    {
      "kind": "Secret",
      "name": "STRIPE_SECRET_KEY"
    },
    {
      "kind": "Secret",
      "name": "RESEND_API_KEY"
    },
    {
      "kind": "Database",
      "name": "mydata"
    }
  ]
}
```

## Getting the Schema

Your AI assistant can retrieve the exact schema for `neptune.json`:

> [!NOTE]
>
> "What's the schema for neptune.json?"

This returns the JSON Schema that defines all valid configuration options.

## Letting AI Handle Configuration

In most cases, you don't need to manually edit `neptune.json`. Just tell your AI assistant what you need:

> [!NOTE]
>
> "Add a storage bucket for user uploads"

> [!NOTE]
>
> "My app runs on port 3000"

Your AI assistant will update the configuration and handle validation automatically.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.