How to add a proxy in Octo Browser

Octo Browser splits proxies into two kinds: saved ones, which count against your plan, and temporary ones attached to a single profile, which do not.

Both take the same pasted string, and Octo accepts an unusually wide range of shapes for it. This covers those, which kind to use when, and how to start a profile over the local client API.

What is Octo Browser?

An anti-detect browser for multi-accounting, operated by Blackbird Secure Browsing Ltd, with a proxy manager and its own proxy shop.

Octo Browser proxy features

Eight templates

The IPv4 set and the IPv6 set, quoted as published:

IPv4                                      IPv6
protocol://login:password@host:port       login:password@[host]:port
protocol://host:port:login:password       [host]:port:login:password
login:password@host:port                  protocol://login:password@[host]:port
host:port:login:password                  protocol://[host]:port:login:password

The square brackets in the IPv6 column are literal. That is the one detail here you cannot guess, and it is the reason an IPv6 proxy that works everywhere else fails to paste.

Both credential orders are accepted, as with every tool in this category, and both with and without the protocol prefix.

Delimiters other than the colon

Claimed on one page: "Delimiters are also supported ( ; , @ , space) in any order."

We could not find a single worked example of that anywhere in their documentation, and we looked at all eighty English pages. Treat it as documented but undemonstrated, and prefer the colon form that the ten worked examples actually use.

Temporary proxies, uncapped

A proxy can be attached to one profile without being saved to the manager: "All subscription tiers support an unlimited number of temporary proxies."

That matters because the saved-proxy count is the thing your plan limits. Lite saves ten, Starter fifty, Base five hundred. Temporary ones do not count.

Protocol coverage

"SOCKS5, HTTPS, HTTP, and SSH protocols are supported." SOCKS4 is absent, which matches MoreLogin and differs from GoLogin and Dolphin Anty.

Proxies with no credentials work too, though it is documented only in passing, through a protocol://ip:port entry in the bulk format list and a worked curl example described as "A proxy that does not require login and password".

Adding a proxy

1. From the profile list, click the Direct button in the Proxy column, then "Set new proxy" at the foot of the drop-down. Leave "Save to proxy list" off for a temporary one.
2. Paste the whole string into the address box. Note the docs give it two different names on two pages, "Enter IP or domain" on one and "Host" on the other, so do not go hunting for a label that matches.

The error strings, and their codes

Octo is the only tool of the seven we have read that gives its proxy errors identifiers. That makes them searchable, which is worth more than it sounds.

"Failed to get proxy data (#CC14, #CD02, #CD03)" is the one people look up. Octo's cause: "This notification is related either to the proxy in the profile or to your Internet connection."

Their fix puts your own connection first: "If you are certain that the proxy is working correctly, try changing the Internet connection", either to mobile internet or through a VPN located in Europe.

Over the local API the same condition arrives as JSON:

{ "code": "profiles.proxy_error", "error": "Failed to get proxy data", "error_code": 4 }

"Proxy connection failed (#FD01)" has a second documented cause worth knowing, because nothing about it suggests a proxy: "Your antivirus may be blocking some Octo Browser components." The fix is an exclusion, not a credential.

"Cannot change proxy IP. Please try later (#CD07)" is about the rotation URL rather than the proxy.

Automating it

Two APIs doing different jobs. The cloud one manages profiles and takes a token header; the local one starts them and takes none.

import requests
from playwright.sync_api import sync_playwright

CLOUD = "https://app.octobrowser.net/api/v2/automation"
LOCAL = "http://localhost:58888/api/v1"
H = {"X-Octo-Api-Token": TOKEN}

# 1. Save a proxy on the cloud side. login/password are optional fields,
#    which is how a credential-free proxy is expressed.
proxy = requests.post(f"{CLOUD}/proxies", headers=H, json={
    "title": "gate",
    "type": "http",
    "host": "gate.example.com",
    "port": 7000,
    "login": "user-session-abc123",
    "password": "secret",
}).json()

# 2. Start the profile locally, asking for a debug port.
r = requests.post(f"{LOCAL}/profiles/start", json={
    "uuid": PROFILE_UUID,
    "headless": True,
    "debug_port": True,      # true = a random free port; an int pins one
    "only_local": True,      # bind 127.0.0.1 only
}).json()

# 3. Connect to what it returned.
with sync_playwright() as pw:
    browser = pw.chromium.connect_over_cdp(r["ws_endpoint"])
    page = browser.contexts[0].pages[0]
    page.goto("https://example.com")
    browser.close()

requests.post(f"{LOCAL}/profiles/stop", json={"uuid": PROFILE_UUID})

The launch response carries both handles:

{
  "ws_endpoint": "ws://127.0.0.1:55834/devtools/browser/a26c9612-6479-43f1-87ef-34590321a99a",
  "debug_port": "55834"
}

The debug port can be pinned, which is unusual here. Everywhere else in this category the port is allocated per launch and the vendor tells you not to hardcode it. Octo lets you choose: "true allocates a random free port", or an integer in the range 1024 to 65534 "pins a specific port".

A proxy failure surfaces over the same local API as JSON rather than as a notification:

{ "code": "profiles.proxy_error", "error": "Failed to get proxy data", "error_code": 4 }

The local API "does not require an X-Octo-Api-Token header, authentication is implicit via the running session of the desktop app", and it "listens on 127.0.0.1:58888 only".

This follows Octo's documented endpoints rather than a run of ours, since there is no free tier to check it on and the API is gated below Base.

The clear-text warning

Quoted in full, because it is the vendor's own words about their own product:

"Security note: proxy login and password are returned in clear text. Avoid logging full responses."

The proxy manager also shows the password as a column in the list. Shop proxies also share credentials across a provider: "The same password is used for all proxies of the same provider, which is important to keep in mind when transferring access rights to proxies. Currently, changing proxy authorization data is available only by request to Customer Service."

None of that is a defect exactly. It is a set of facts about where your proxy credentials end up, and the honest thing is that Octo states them and its competitors do not.

Plans, and the absence of a free tier

Five paid plans, starting at Lite for ten euros a month with three profiles. We checked the rendered pricing page for a zero-cost card and there is none.

A trial exists and is not self-serve: "New users may be occasionally offered a trial subscription. To ask for a trial period possibility, you need to contact the Octo Customer Service Telegram bot."

This is the only tool of the seven we have read with no free path at all. If you want to test a proxy against an anti-detect browser before paying, MoreLogin is currently the one that lets you script it for nothing.

Whichever tool you settle on, the proxy behind it is the recurring cost, and per-gigabyte prices vary far more between providers than these applications vary between each other. What each charges, with the date it was read, is on the provider table.

Limitations

Saved proxies are capped by plan, from ten on Lite to twenty thousand on Advanced. Exceeding it returns proxy.maximum_saved_error.

Shop proxies die with the subscription: "Once your Octo Browser subscription expires, you cannot create a proxy even if you still have unused traffic left."

Proxifier mode is explicitly unsupported: "No testing of browser components in the proxifier mode has been performed."

What the documentation does not say

• Whether IP allowlisting works at all. We searched all eighty English pages plus the API reference for whitelist, allowlist, IP authorisation and IP binding. Nothing establishes that an allowlisted proxy can be used, and no Octo egress range is published to allowlist.
• Whether the alternative delimiters actually parse. Claimed on one page, demonstrated on none.
• Whether a label can be appended to the string. No suffix convention is documented, unlike GoLogin and Dolphin Anty which both take a trailing name.

With eight accepted templates Octo will parse almost anything, including a wrong thing into the wrong field. The session token sits in the login segment at some providers and the password at others, which no format can settle for you. What each states is on its provider page, dated.

Conclusion

Octo documents more than its competitors and is franker about the uncomfortable parts, which is worth crediting. Use the colon form rather than the claimed alternative delimiters, remember the literal brackets on IPv6, and read the clear-text note before you pipe an API response into a log file.