Proxy support

DataMind Oda can reach the internet through an HTTP proxy. It reads the proxy settings that programs on this computer use; this page covers which settings it reads, where their values come from, how one request is routed, what always stays direct, and what the programs Oda starts receive.

Set up a proxy

1. Choose where the values live: the environment you launch Oda from, or the Oda home folder's .env file. An exported value always wins over the file.
2. Set http_proxy for ordinary requests and https_proxy for secure ones, or the general all_proxy for both. Each value is the proxy's address, for example http://proxy.example.com:8080. If the proxy needs a user name and password, put them in the address itself, before the host.
3. If your proxy inspects secure traffic, add its certificate to the extra trusted certificates in the environment you launch Oda from. That list is read only when a program starts.
4. Start Oda again. The values are read once, when Oda starts, so a change applies from the next start.

Which settings Oda reads

• Program settings, not system settings. Oda reads the proxy variables set for programs; it does not read your operating system's proxy settings.
• Four settings. http_proxy for ordinary requests, https_proxy for secure requests, all_proxy as a general address that backs both, and no_proxy as the list of addresses to leave alone.
• Lower case first. The lower-case spelling is read first and the upper-case spelling is used only when the lower-case name is not set; on Windows the two spellings are read as one name. A name that is set but empty counts as unset.
• A kind's own setting wins. For each kind of request Oda looks at that kind's setting first, then at the general address; a secure request falls back to the ordinary address last.

Where and when the values are read

• Your environment first. The value you export where you launch Oda is used first; if your environment sets none, Oda uses the value saved in the Oda home folder's .env.
• Not from a project folder. A .env file in the folder you launch from may not set these names, so a project can never decide where your traffic goes. Startup and diagnostics has the file rules, and Where Oda keeps its data covers the home folder itself.
• Read once, at launch. The values are taken once, when Oda starts, and the route is in place before Oda's parts load. They do not change while it runs, not even when you open another chat or switch folders.
• Nothing is left changed. The route is fully undone when the run ends; Oda changes nothing in your computer's own settings. A run that turns proxying off goes direct until it ends, and then your settings return.

How one request is routed

1. This computer's own addresses stay direct. localhost, the whole 127.0.0.0/8 range, ::1, 0.0.0.0, and the IPv4-mapped spellings of those never go through the proxy; you do not need to list them. A proxy that also served these addresses would send Oda's local traffic in a loop, so the exception is not optional.
2. Your leave-alone list is checked next. A destination on it goes direct.
3. Then the settings decide. Oda looks at the setting for the request's kind, then at the general address; a secure request falls back to the ordinary address last. When nothing is set, the request goes direct.
4. A refused value ends the search. When the setting found cannot be used, that kind of request goes direct; it is never sent to another setting's address.

Oda's model calls, web searches and page reads all use the route, as do the programs Oda runs.

The leave-alone list

• A host and everything under it. An entry names a host and covers it together with every name under it: example.com also covers api.example.com. Case does not matter.
• Plain, dotted and starred forms. A leading . or *. is accepted and means the same as the plain host, and a single * leaves every request direct.
• A port narrows an entry. An entry may carry a port and then covers only that port; an entry without one covers the host on every port.
• Separators. Entries are separated by commas or spaces, and a blank entry is ignored.
• No ranges. A range such as 10.0.0.0/8 does not match; write each address separately.
• Built-in entries. Oda adds this computer's own addresses to the list it applies, so you never need to write them into it. A single * is kept as written.

When a value cannot be used

• Web addresses only. A proxy address must begin with http:// or https:// and parse as an address. A SOCKS address, a PAC address, or a value that cannot be read is not usable.
• Noted once, never echoed. Oda notes the setting that has the problem once, and never the value you wrote, so a password inside an address does not appear in the note.
• Skipped, not replaced. The setting is skipped and that kind of request connects directly. Oda never swaps in another setting's address for it, and your other settings keep working.
• Nothing stops. A value Oda cannot use never stops Oda from starting.

What the programs Oda starts receive

• Your value, your spelling. A setting you wrote yourself reaches a program exactly as you wrote it, spelling included. A kind you did not set carries the value Oda resolved.
• The general address is completed. When only all_proxy is set, Oda also fills it into http_proxy and https_proxy, because programs read those names.
• The leave-alone list always applies. Programs receive the resolved list: your entries plus this computer's own addresses, so nothing you wrote is lost.
• A password can travel with it. The address is part of the environment, so the programs Oda starts can read a password inside it, and it can end up in output that is kept. Prefer a proxy entry point that needs no password where one is available.
• Still starts. A program that reads these settings at start-up starts even when one of the values is one Oda skipped; where it cannot use the value either, it connects directly.

Command environment and containment covers what a command sees of your settings.

When Oda cannot reach the internet through your proxy

1. Check that the address begins with http:// or https:// and parses as an address.
2. A note that a value was skipped names the setting that has the problem; fix that value, and remember that your other settings keep working.
3. Check that the right kind is set: the general address backs both kinds, and a secure request falls back to the ordinary address last.
4. Check that the value sits in the environment you launch Oda with or in the Oda home folder's .env, and that Oda was started again after the change.
5. If your proxy inspects secure traffic, its certificate must be trusted before the next start.

Questions, answered

Which settings does Oda read for the proxy?

http_proxy for ordinary requests, https_proxy for secure requests, all_proxy as a general address that backs both, and no_proxy as the list of addresses to leave alone. The lower-case spelling is read first and the upper-case one is used only when the lower-case name is not set; on Windows the two spellings are read as one name. A name that is set but empty counts as unset.

Why does my browser use a proxy while Oda does not?

A browser follows the proxy settings of your operating system. Oda does not read those; it reads the proxy variables your computer sets for programs instead. Set the value there, or in the Oda home folder's .env, and start Oda again.

Do I have to restart Oda after I change a proxy setting?

Yes. Oda reads the values once, when it starts, and keeps them for the whole run; opening a new chat or switching folders changes nothing. A change, or a removed value, applies from the next start.

What happens when only all_proxy is set?

The general address backs both kinds of request. For each kind Oda still looks at the setting for that kind first, and a secure request falls back to the ordinary address last. A setting Oda refused is the exception: that kind connects directly instead of borrowing another setting's address.

Can a project folder set my proxy?

No. A .env file in the folder you launch from may not set these names; set the value in the environment you launch Oda with, or in the Oda home folder's .env. When both hold a value, the exported one wins. Startup and diagnostics has the full rules for the files.

Does traffic to my company network go through the proxy?

Oda does not exempt it. Only this computer's own addresses are always direct; an address on your company network takes the same route as any other request unless you add it to the leave-alone list. Reading web pages is separate: the built-in page reader refuses private addresses on its own rules, whether or not a proxy is set, as Anonymous web fetch safety explains.

Which proxy addresses does Oda accept?

An address that begins with http:// or https:// and parses as an address. A SOCKS address, a PAC address, or a value that cannot be read as an address is noted once when Oda starts, skipped, and that kind of request connects directly; Oda never replaces it with another setting's address. The note names the setting that has the problem, never the value you wrote.

Can my proxy address include a user name and password?

Yes. Put the credentials in the address itself, before the host. Oda never prints the address back, so a password inside it does not appear in its notes. The address is part of your environment, though: the programs Oda runs can see it, and it can end up in output that is kept. Prefer a proxy entry point that needs no password where one is available.

Why does a program see my general address under http_proxy and https_proxy?

Because programs read the per-kind names. When you set only the general address, Oda also fills it into http_proxy and https_proxy, so commands and helper tools that follow the environment route like Oda does. A setting you wrote yourself reaches a program exactly as you wrote it, spelling included, and the leave-alone list a program receives is always the resolved one.

I listed a host to leave alone, but requests to it still used the proxy. Why?

Check three things. If you changed the list after Oda started, start Oda again: the list is read once, at launch. If the entry carries a port, it covers only that port, so a request to another port still uses the proxy. And a range entry such as 10.0.0.0/8 matches nothing; write each address separately.

How do I check that Oda uses my proxy?

Watch your proxy's own connection log while Oda does something that reaches the internet, such as reading a public page: the connection should appear there. If it does not, confirm the values are visible to the environment you launch Oda from, then start Oda again; the values are read once, when it starts.

Our proxy inspects secure traffic. Is anything else needed?

Yes. The proxy's certificate must be added to the list of extra trusted certificates, and that list is read only when a program starts. Set it up before you start Oda; anything added later applies at the next start.