Skip to main content
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

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

​
Configuration Reference

​
Required Fields

FieldTypeDescription
kindstringMust be "Service"
namestringUnique project name (lowercase, hyphens allowed)

​
Optional Fields

FieldTypeDefaultDescription
port_mappingsarray[{container_port: 8080, host_port: 8080}]Port mappings for your container
resourcesarray[]Storage buckets and secrets

​
Port Mappings

Map your container’s port to the external port: 
{
  "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"
If your app listens on port 8080, you don’t need to specify port mappings - that’s the default.

​
CPU and Memory

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: 
{
  "resources": [
    {
      "kind": "StorageBucket",
      "name": "uploads"
    },
    {
      "kind": "Secret",
      "name": "API_KEY"
    }
  ]
}

Storage Buckets

Secrets

​
Complete Example

neptune.json
{
  "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"
    }
  ]
}

​
Getting the Schema

Your AI assistant can retrieve the exact schema for neptune.json:
“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:
“Add a storage bucket for user uploads”
“My app runs on port 3000”
Your AI assistant will update the configuration and handle validation automatically.