Make your first proxy connection with a check you can repeat

Prepare the two public files

1. Check the installed runtimes

   This recipe was verified with Node.js 24.14.0 and curl 8.13.0 on Windows. It uses only Node built-ins and curl, with no package installation. Confirm node --version and curl.exe --version in PowerShell/cmd; use curl --version in a POSIX shell.

2. Save the local fixture

   Save the linked local-first-connection-v1.mjs file in a new directory. Save the full “Request example” below as example.mjs beside it. Read both files before running; this runner is not a sandbox for arbitrary code.

3. Run from that directory

   Use the launch command below in PowerShell, cmd or a POSIX shell. The runner starts a proxy and an origin on loopback with temporary ports and sends synthetic input privately to example.mjs.

4. Read the control results

   An overall exit of 0 means the success, wrong-credential and bypass controls matched. The runner closes both listeners. Any nonzero overall exit needs investigation; a missing client is not an authentication rejection.

Download the bounded fixture

The fixture forwards only GET to its own exact local /echo address and does not support CONNECT. It never calls a platform, changes an account or installs a client. No real credential or protected-config file is needed for the exercise.

The downloaded runner supplies proxy, username, password, target and bypass to the example on stdin. The example passes curl configuration through a private pipe as `curl -q --config -`; -q is the first curl argument so a default curlrc cannot silently change the request. On Windows it selects curl.exe, not a PowerShell alias. CURL_BIN can select an already trusted curl executable.

• Save local-first-connection-v1.mjs

• curl manual: config, proxy-user and SOCKS5 DNS

Launch all three controls

Scroll horizontally with the arrow keys to read all content.

node local-first-connection-v1.mjs example.mjs

Run in the directory holding the two saved files. This command uses no shell input redirection and works in PowerShell, cmd and POSIX shells.

Checked with a local fixture

• Local curl first-connection controls

Request example

Scroll horizontally with the arrow keys to read all content.

import { readFileSync } from 'node:fs'
import { spawn } from 'node:child_process'

let cfg
try {
  cfg = JSON.parse(readFileSync(0, 'utf8'))
  if (!cfg || typeof cfg.bypass !== 'boolean' ||
      ['proxy','username','password','target'].some(key =>
        typeof cfg[key] !== 'string' || /[\r\n]/.test(cfg[key]))) throw new Error()
} catch {
  console.log(JSON.stringify({error:'invalid-input'}))
  process.exit(1)
}
const quote = value => {
  return '"' + value.replaceAll('\\', '\\\\').replaceAll('"', '\\"') + '"'
}
const curl = process.env.CURL_BIN || (process.platform === 'win32' ? 'curl.exe' : 'curl')
const config = [
  'proxy = ' + quote(cfg.proxy),
  'proxy-user = ' + quote(cfg.username + ':' + cfg.password),
  'noproxy = ' + quote(cfg.bypass ? '*' : ''),
  'url = ' + quote(cfg.target),
  'silent',
  'fail',
  'connect-timeout = 3',
  'max-time = 5',
  'write-out = "\\n%{http_code}"',
].join('\n')
const child = spawn(curl, ['-q', '--config', '-'], { stdio: ['pipe','pipe','pipe'], windowsHide:true })
let output = '', startFailed = false
child.stdout.setEncoding('utf8')
child.stdout.on('data', chunk => { output += chunk })
child.stderr.resume()
child.stdin.on('error', () => {})
child.on('error', () => {
  startFailed = true
  console.log(JSON.stringify({error:'runtime-unavailable'}))
  process.exitCode = 1
})
child.on('close', code => {
  if (startFailed) return
  const match = output.match(/\n(\d{3})$/)
  if (!match) {
    console.log(JSON.stringify({error:'runtime-invalid'}))
    process.exitCode = 1
    return
  }
  const http_status = Number(match[1])
  const body = output.slice(0, match.index)
  const marker = body === 'first-connection-fixture'
  console.log(JSON.stringify({http_status,curl_exit:code,marker}))
  process.exitCode = code === 0 && http_status === 200 && marker ? 0 : 1
})
child.stdin.end(config)

Save as example.mjs. Node starts curl with only -q --config - in argv; the synthetic configuration travels on stdin. Error bodies and raw curl diagnostics are not printed.

Checked with a local fixture

• Local curl first-connection controls
• curl manual: config, proxy-user and SOCKS5 DNS

Expected local evidence

Scroll horizontally with the arrow keys to read all content.

The runner itself exits 0 only when all three expected outcomes match. These counters belong to a controlled HTTP fixture, not a production exit check.

• Local curl first-connection controls

Match protocol and authentication

Scroll horizontally with the arrow keys to read all content.

The DNS distinction describes curl's selected option or URL scheme, not an unconditional property of the SOCKS5 protocol.

• curl manual: config, proxy-user and SOCKS5 DNS

When you move to real connection details

Use a read-only endpoint you own or are authorized to test. Obtain the exact protocol, host, port and proxy authentication details from the connection information you are allowed to use. Do not substitute a paid API as a connectivity probe.

For a manually maintained curl config, store proxy and proxy-user in a local file accessible only to your OS user, then pass its filename to curl's --config option. Restrict permissions before adding secrets (owner-only permissions on POSIX; a user-only ACL on Windows), keep it outside shared/synced folders and version control, and remove it when finished. This page does not supply or verify a platform-specific permission command.

Do not expand a password environment variable into command arguments. Avoid verbose/trace output, screenshots of configuration and raw diagnostics. Proxy authentication is separate from destination authorization. A real exit check needs an authorized endpoint's observed client address and the intended proxy record; this local example establishes neither a real country nor third-party compatibility.

• curl manual: config, proxy-user and SOCKS5 DNS

Interpret failures before changing an exit

Choose the next guide

If you only needed to establish a curl route, stop after the paired check. Browser automation and standalone API clients have separate settings. Keep direct access when it already meets the task; a proxy adds another connection to diagnose.

• Browser requests with Playwright
• Browser requests with Selenium
• Choose a working scenario
• Compare proxy types