> ## 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.

# Quickstart

> Deploy your first app to Neptune in under 5 minutes

Get your application deployed to the cloud through a simple conversation with your AI coding assistant.

## Prerequisites

Before you begin, make sure you have:

* **Docker** - For building your application container
* An AI coding assistant that supports the Model Context Protocol (MCP): e.g. [Cursor](https://docs.neptune.dev/ai-tools/cursor.md), [Claude Code](https://docs.neptune.dev/ai-tools/claude-code.md), or [Windsurf](https://docs.neptune.dev/ai-tools/windsurf.md)

## Step 1: Install the Neptune MCP

Choose your preferred installation method and AI coding assistant:

> [!TIP]
>
> **Tested models:** Neptune works well with Sonnet 4.5, Opus 4.5, GPT 5.1
> (including Codex/Codex-mini), Gemini 3 Pro, Cursor Compose 1, and Grok Code.
> Other models may work but haven't been extensively tested.

> [tab] Neptune Binary (Recommended)
>
> First, install the Neptune MCP:
>
> > [tab] macOS / Linux
> >
> > ```bash theme={"dark"}
> > curl -fsSL https://neptune.dev/install.sh | bash
> > ```
>
> > [tab] Windows
> >
> > ```bash theme={"dark"}
> > irm https://neptune.dev/install.ps1 | iex
> > ```
>
> Then configure your AI coding assistant:
>
> > [accordion] Cursor
> >
> > 1. Open **Cursor Settings** → **Tools & MCP** → **Add new MCP server**
> > 2. Add this configuration:
> >
> > ```json theme={"dark"}
> > {
> >   "mcpServers": {
> >     "neptune": {
> >       "command": "neptune",
> >       "args": ["mcp"]
> >     }
> >   }
> > }
> > ```
> >
> > 3. Restart Cursor
>
> > [accordion] Claude Code (CLI)
> >
> > Run this command in your terminal:
> >
> > ```bash theme={"dark"}
> > claude mcp add --transport stdio neptune -- neptune mcp
> > ```
> >
> > Verify it was added:
> >
> > ```bash theme={"dark"}
> > claude mcp list
> > ```
> >
> > > [!TIP]
> > >
> > > Use `--scope user` to make Neptune available across all projects, or `--scope project` to share with your team via `.mcp.json`.
>
> > [accordion] Windsurf
> >
> > 1. Open **Windsurf Settings** → **Cascade** → **Plugins** → **Manage plugins**
> > 2. Edit `~/.codeium/windsurf/mcp_config.json` and add:
> >
> > ```json theme={"dark"}
> > {
> >   "mcpServers": {
> >     "neptune": {
> >       "command": "neptune",
> >       "args": ["mcp"]
> >     }
> >   }
> > }
> > ```
> >
> > 3. Press the **refresh button** in the Plugins panel, then reload Windsurf
> >
> > [Official Windsurf MCP docs →](https://docs.windsurf.com/windsurf/cascade/mcp)
>
> > [accordion] VS Code (Cline Extension)
> >
> > 1. Install the [Cline extension](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev)
> > 2. Click the **MCP Servers** icon in the Cline panel → **Configure** tab → **Configure MCP Servers**
> > 3. Add this to your `cline_mcp_settings.json`:
> >
> > ```json theme={"dark"}
> > {
> >   "mcpServers": {
> >     "neptune": {
> >       "command": "neptune",
> >       "args": ["mcp"]
> >     }
> >   }
> > }
> > ```
> >
> > 4. Reload VS Code
> >
> > [Official Cline MCP docs →](https://docs.cline.bot/mcp/configuring-mcp-servers)
>
> > [accordion] VS Code (GitHub Copilot)
> >
> > 1. Run **MCP: Open User Configuration** from the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`)
> > 2. Add this to your `mcp.json`:
> >
> > ```json theme={"dark"}
> > {
> >   "servers": {
> >     "neptune": {
> >       "command": "neptune",
> >       "args": ["mcp"]
> >     }
> >   }
> > }
> > ```
> >
> > > [!TIP]
> > >
> > > Use **MCP: Open Remote User Configuration** if you want the server to run on a remote machine when connected remotely.
> >
> > 3. Reload VS Code
> >
> > [Official VS Code MCP docs →](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)
>
> > [accordion] JetBrains IDEs (IntelliJ, PyCharm, WebStorm, etc.)
> >
> > 1. Open **Settings** → **Tools** → **AI Assistant** → **Model Context Protocol (MCP)**
> > 2. Click **Add** and select **As JSON**, then paste:
> >
> > ```json theme={"dark"}
> > {
> >   "mcpServers": {
> >     "neptune": {
> >       "command": "neptune",
> >       "args": ["mcp"]
> >     }
> >   }
> > }
> > ```
> >
> > 3. Set **Level** to "Global" to use Neptune across all projects, then click **Apply**
> >
> > > [!TIP]
> > >
> > > Already use Claude Desktop? Click **Import from Claude** to reuse your existing MCP configs.
> >
> > [Official JetBrains MCP docs →](https://www.jetbrains.com/help/ai-assistant/mcp.html)
>
> > [accordion] Warp Terminal
> >
> > 1. Open **Settings** → **MCP Servers** (or via Warp Drive → Personal → MCP Servers)
> > 2. Click **+ Add** and paste this configuration:
> >
> > ```json theme={"dark"}
> > {
> >   "mcpServers": {
> >     "neptune": {
> >       "command": "neptune",
> >       "args": ["mcp"]
> >     }
> >   }
> > }
> > ```
> >
> > 3. Click **Start** on the Neptune server to enable it
> >
> > [Official Warp MCP docs →](https://docs.warp.dev/knowledge-and-collaboration/mcp)
>
> > [accordion] Other MCP Clients (Generic STDIO)
> >
> > For any MCP client that supports STDIO transport, use this command:
> >
> > ```bash theme={"dark"}
> > neptune mcp
> > ```
> >
> > Configure your client to run this command and communicate via stdin/stdout.
>
> > [accordion] HTTP Transport (Alternative)
> >
> > If your client doesn't support STDIO or you prefer HTTP, start the MCP server in HTTP mode:
> >
> > ```bash theme={"dark"}
> > neptune mcp --transport=http
> > ```
> >
> > The server runs at `http://localhost:8001/mcp`. Configure your client to connect to this URL.

> [tab] Python + uv
>
> First, install uv and Python 3.13+:
>
> > [tab] macOS
> >
> > ```bash theme={"dark"}
> > # Install uv
> > brew install uv
> >
> > # Or via curl
> >
> > curl -LsSf https://astral.sh/uv/install.sh | sh
> >
> > ```
>
> > [tab] Linux
> >
> > ```bash theme={"dark"}
> > curl -LsSf https://astral.sh/uv/install.sh | sh
> > ```
>
> > [tab] Windows
> >
> > ```powershell theme={"dark"}
> > powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
> > ```
>
> Then configure your AI coding assistant:
>
> > [accordion] Cursor
> >
> > 1. Open **Cursor Settings** → **Tools & MCP** → **Add new MCP server**
> >
> > 2. Add this configuration:
> >
> > > [tab] macOS / Linux
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "mcpServers": {
> > >     "neptune": {
> > >       "command": "uvx",
> > >       "args": [
> > >         "--from",
> > >         "git+https://github.com/shuttle-hq/neptune-mcp.git",
> > >         "neptune",
> > >         "mcp"
> > >       ]
> > >     }
> > >   }
> > > }
> > > ```
> >
> > > [tab] Windows
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "mcpServers": {
> > >     "neptune": {
> > >       "command": "cmd",
> > >       "args": [
> > >         "/c",
> > >         "uvx",
> > >         "--from",
> > >         "git+https://github.com/shuttle-hq/neptune-mcp.git",
> > >         "neptune",
> > >         "mcp"
> > >       ]
> > >     }
> > >   }
> > > }
> > > ```
> >
> > 3. Restart Cursor
>
> > [accordion] Claude Code (CLI)
> >
> > Run this command in your terminal:
> >
> > > [tab] macOS / Linux
> > >
> > > ```bash theme={"dark"}
> > > claude mcp add --transport stdio neptune -- uvx --from git+https://github.com/shuttle-hq/neptune-mcp.git neptune mcp
> > > ```
> >
> > > [tab] Windows
> > >
> > > ```bash theme={"dark"}
> > > claude mcp add --transport stdio neptune -- cmd /c uvx --from git+https://github.com/shuttle-hq/neptune-mcp.git neptune mcp
> > > ```
> >
> > Verify it was added:
> >
> > ```bash theme={"dark"}
> > claude mcp list
> > ```
> >
> > > [!TIP]
> > >
> > > Use `--scope user` to make Neptune available across all projects, or `--scope project` to share with your team via `.mcp.json`.
>
> > [accordion] Windsurf
> >
> > 1. Open **Windsurf Settings** → **Cascade** → **Plugins** → **Manage plugins**
> >
> > 2. Edit `~/.codeium/windsurf/mcp_config.json` and add:
> >
> > > [tab] macOS / Linux
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "mcpServers": {
> > >     "neptune": {
> > >       "command": "uvx",
> > >       "args": [
> > >         "--from",
> > >         "git+https://github.com/shuttle-hq/neptune-mcp.git",
> > >         "neptune",
> > >         "mcp"
> > >       ]
> > >     }
> > >   }
> > > }
> > > ```
> >
> > > [tab] Windows
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "mcpServers": {
> > >     "neptune": {
> > >       "command": "cmd",
> > >       "args": [
> > >         "/c",
> > >         "uvx",
> > >         "--from",
> > >         "git+https://github.com/shuttle-hq/neptune-mcp.git",
> > >         "neptune",
> > >         "mcp"
> > >       ]
> > >     }
> > >   }
> > > }
> > > ```
> >
> > 3. Press the **refresh button** in the Plugins panel, then reload Windsurf
> >
> > [Official Windsurf MCP docs →](https://docs.windsurf.com/windsurf/cascade/mcp)
>
> > [accordion] VS Code (Cline Extension)
> >
> > 1. Install the [Cline extension](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev)
> >
> > 2. Click the **MCP Servers** icon in the Cline panel → **Configure** tab → **Configure MCP Servers**
> >
> > 3. Add this to your `cline_mcp_settings.json`:
> >
> > > [tab] macOS / Linux
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "mcpServers": {
> > >     "neptune": {
> > >       "command": "uvx",
> > >       "args": [
> > >         "--from",
> > >         "git+https://github.com/shuttle-hq/neptune-mcp.git",
> > >         "neptune",
> > >         "mcp"
> > >       ]
> > >     }
> > >   }
> > > }
> > > ```
> >
> > > [tab] Windows
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "mcpServers": {
> > >     "neptune": {
> > >       "command": "cmd",
> > >       "args": [
> > >         "/c",
> > >         "uvx",
> > >         "--from",
> > >         "git+https://github.com/shuttle-hq/neptune-mcp.git",
> > >         "neptune",
> > >         "mcp"
> > >       ]
> > >     }
> > >   }
> > > }
> > > ```
> >
> > 4. Reload VS Code
> >
> > [Official Cline MCP docs →](https://docs.cline.bot/mcp/configuring-mcp-servers)
>
> > [accordion] VS Code (GitHub Copilot)
> >
> > 1. Run **MCP: Open User Configuration** from the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`)
> >
> > 2. Add this to your `mcp.json`:
> >
> > > [tab] macOS / Linux
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "servers": {
> > >     "neptune": {
> > >       "command": "uvx",
> > >       "args": [
> > >         "--from",
> > >         "git+https://github.com/shuttle-hq/neptune-mcp.git",
> > >         "neptune",
> > >         "mcp"
> > >       ]
> > >     }
> > >   }
> > > }
> > > ```
> >
> > > [tab] Windows
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "servers": {
> > >     "neptune": {
> > >       "command": "cmd",
> > >       "args": [
> > >         "/c",
> > >         "uvx",
> > >         "--from",
> > >         "git+https://github.com/shuttle-hq/neptune-mcp.git",
> > >         "neptune",
> > >         "mcp"
> > >       ]
> > >     }
> > >   }
> > > }
> > > ```
> >
> > > [!TIP]
> > >
> > > Use **MCP: Open Remote User Configuration** if you want the server to run on a remote machine when connected remotely.
> >
> > 3. Reload VS Code
> >
> > [Official VS Code MCP docs →](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)
>
> > [accordion] JetBrains IDEs (IntelliJ, PyCharm, WebStorm, etc.)
> >
> > 1. Open **Settings** → **Tools** → **AI Assistant** → **Model Context Protocol (MCP)**
> >
> > 2. Click **Add** and select **As JSON**, then paste:
> >
> > > [tab] macOS / Linux
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "mcpServers": {
> > >     "neptune": {
> > >       "command": "uvx",
> > >       "args": [
> > >         "--from",
> > >         "git+https://github.com/shuttle-hq/neptune-mcp.git",
> > >         "neptune",
> > >         "mcp"
> > >       ]
> > >     }
> > >   }
> > > }
> > > ```
> >
> > > [tab] Windows
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "mcpServers": {
> > >     "neptune": {
> > >       "command": "cmd",
> > >       "args": [
> > >         "/c",
> > >         "uvx",
> > >         "--from",
> > >         "git+https://github.com/shuttle-hq/neptune-mcp.git",
> > >         "neptune",
> > >         "mcp"
> > >       ]
> > >     }
> > >   }
> > > }
> > > ```
> >
> > 3. Set **Level** to "Global" to use Neptune across all projects, then click **Apply**
> >
> > > [!TIP]
> > >
> > > Already use Claude Desktop? Click **Import from Claude** to reuse your existing MCP configs.
> >
> > [Official JetBrains MCP docs →](https://www.jetbrains.com/help/ai-assistant/mcp.html)
>
> > [accordion] Warp Terminal
> >
> > 1. Open **Settings** → **MCP Servers** (or via Warp Drive → Personal → MCP Servers)
> >
> > 2. Click **+ Add** and paste this configuration:
> >
> > > [tab] macOS / Linux
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "mcpServers": {
> > >     "neptune": {
> > >       "command": "uvx",
> > >       "args": [
> > >         "--from",
> > >         "git+https://github.com/shuttle-hq/neptune-mcp.git",
> > >         "neptune",
> > >         "mcp"
> > >       ]
> > >     }
> > >   }
> > > }
> > > ```
> >
> > > [tab] Windows
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "mcpServers": {
> > >     "neptune": {
> > >       "command": "cmd",
> > >       "args": [
> > >         "/c",
> > >         "uvx",
> > >         "--from",
> > >         "git+https://github.com/shuttle-hq/neptune-mcp.git",
> > >         "neptune",
> > >         "mcp"
> > >       ]
> > >     }
> > >   }
> > > }
> > > ```
> >
> > 3. Click **Start** on the Neptune server to enable it
> >
> > [Official Warp MCP docs →](https://docs.warp.dev/knowledge-and-collaboration/mcp)
>
> > [accordion] Other MCP Clients (Generic STDIO)
> >
> > For any MCP client that supports STDIO transport, use this command:
> >
> > ```bash theme={"dark"}
> > uvx --from git+https://github.com/shuttle-hq/neptune-mcp.git neptune mcp
> > ```
> >
> > Configure your client to run this command and communicate via stdin/stdout.
>
> > [accordion] HTTP Transport (Alternative)
> >
> > If your client doesn't support STDIO or you prefer HTTP, start the MCP server in HTTP mode:
> >
> > ```bash theme={"dark"}
> > uvx --from git+https://github.com/shuttle-hq/neptune-mcp.git neptune mcp --transport=http
> > ```
> >
> > The server runs at `http://localhost:8001/mcp`. Configure your client to connect to this URL.

## Step 2: Authenticate

Once the MCP is installed, ask your AI assistant:

> [!NOTE]
>
> "Log me in to Neptune"

A browser window will open for GitHub OAuth authentication. Sign in with your GitHub account and you're ready to deploy.

## Step 3: Deploy Your App

Simply ask your AI assistant:

> [!NOTE]
>
> "Deploy this app to Neptune"

Your AI assistant will:

1. Create an optimized `Dockerfile` for your project (if you don't have one)
2. Generate a `neptune.json` configuration
3. Provision any required cloud resources
4. Build and deploy your application

> [!TIP]
>
> No Dockerfile? No problem. Neptune provides context to your AI assistant so it
> can generate one automatically based on your project structure.

## Step 4: Wait for Your App to Go Live

Deployments take a moment to start. Ask your AI assistant:

> [!NOTE]
>
> "Wait for my deployment to complete"

Your AI assistant will monitor the deployment status and let you know when it's ready with your **public IP address**. This typically takes 1-2 minutes.

> [!WARNING]
>
> Don't skip this step! Your app won't be accessible until the deployment has
> finished starting up.

## What Can You Deploy?

Neptune can deploy **any containerized application**. If it runs in Docker, it runs on Neptune.

## Next Steps

> [card] [Add Storage](https://docs.neptune.dev/resources/storage.md)
>
> S3-compatible storage for files and assets

> [card] [Add Secrets](https://docs.neptune.dev/resources/secrets.md)
>
> Securely store API keys and tokens

> [card] [View Logs](https://docs.neptune.dev/deployments/logs-monitoring.md)
>
> Monitor your application

> [!NOTE]
>
> **Need help?** Join our [Discord community](https://discord.gg/kVyP2Fw4sE) for
> support and to connect with other developers.


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