Skip to main content
Neptune is designed to be the simplest path from code to cloud. Here’s how it works under the hood.

​
The Neptune Model

1

You ask your AI assistant to deploy

Just say “Deploy this app to Neptune” - your AI assistant handles the rest.
2

Neptune generates your configuration

Your AI creates an optimized Dockerfile (if needed) and a neptune.json configuration based on your project.
3

Resources are provisioned

Storage buckets and secrets are created automatically in the cloud.
4

Your app is deployed

Neptune builds your container image, pushes it to a private registry, and deploys it.
5

You get a public IP

Your app is live and connected to all your resources.

​
The MCP Connection

Neptune uses the Model Context Protocol (MCP) to connect with your AI coding assistant. MCP is an open standard created by Anthropic that lets AI tools interact with external services. When you install the Neptune MCP, your AI assistant gains access to tools that can:
  • Authenticate you with Neptune via GitHub OAuth
  • Generate Dockerfiles optimized for your project
  • Create neptune.json configurations automatically
  • Provision cloud resources (storage buckets, secrets)
  • Build and deploy your application
  • Monitor deployment status and retrieve logs
This means you can manage your entire deployment lifecycle through natural conversation.
Learn more about MCP: Official Documentation · GitHub · Anthropic Announcement

​
Configuration

Neptune uses a neptune.json file to define your project. Your AI assistant creates and manages this automatically:
neptune.json
{
  "kind": "Service",
  "name": "my-app",
  "resources": [
    {
      "kind": "StorageBucket",
      "name": "uploads"
    },
    {
      "kind": "Secret",
      "name": "API_KEY"
    }
  ]
}
You can also specify compute resources and port mappings:
neptune.json
{
  "kind": "Service",
  "name": "my-app",
  "cpu": "512",
  "memory": "1024",
  "port_mappings": [
    { "container_port": 3000, "host_port": 8080 }
  ]
}

​
How Resources Work

When Neptune provisions resources, it creates them with unique physical names for global uniqueness. Your AI assistant receives these names and can use them when writing code for you.
ResourceWhat Neptune CreatesHow You Access It
StorageBucketS3 bucket (e.g., neptune-abc123-uploads)boto3.client("s3") with the physical bucket name
SecretAWS Secrets Manager secret (e.g., neptune-abc123-API_KEY)boto3.client("secretsmanager") with the physical secret name
All IAM permissions are pre-configured, so you can use standard AWS SDKs like boto3 without any credential setup.

​
Security

  • Authentication: GitHub OAuth - no separate Neptune account needed
  • Secrets: Encrypted at rest in AWS Secrets Manager
  • Network: All traffic is encrypted with TLS
  • Isolation: Each project runs in its own isolated environment
  • IAM: Services only have access to their own resources